Roadmap

midgard.admin.sitewizard

Mon, 14 Jul 2008 20:34:26 +0000

midgard.admin.sitewizard is the site creation and configuration tool in MidCOM.

Installation

Midgard Site Wizard may be installed from PEAR packages. To get it running, generate a website for it using the following command:

# php /usr/share/php/midcom/lib/midgard/admin/sitegroup/bin/create-host.php -c databasename -u admin -p password --sitegroup_id 0 --topic_midcom midgard.admin.sitewizard --hostname www.example.net --host_prefix /sitewizard --extend_style template_Midgard --topic_name "Midgard Site Wizard"

After this Midgard Site Wizard should be available in http://www.example.net/sitewizard/.

The 'datagard' package in Midgard 1.8 performs the installation and setup for you.

Usage

Midgard Site Wizard can be found by accessing the Midgard Welcome Site which is typically installed to the /midgard subdirectory of a Midgard server. Click the login link in the right-hand bar to enter the Wizard:

Site Wizard login link

After authenticating as Midgard Administrator, the first screen of the Wizard will appear. Here it will be possible to either create a new sitegroup virtual database, or set up a new site to an existing one.

You can also define an administrative user account and a disk quota for the sitegroup.

Create organization with Site Wizard

Once the organization has been created or selected, the next screen is for creating a website. Here it is possible to input hostname, port and possible directory prefix for the new site.

Create website with Site Wizard

For the newly-created host to be served it must also be added to Apache VirtualHost configuration. Once this has been done, the next step is to select a style template for the site:

Select style for a Midgard site

After style has been selected, the site should be ready for content management.

Midgard Documentation

Tue, 08 Jul 2008 15:21:38 +0000

Midgard Documentation is a Wiki collecting information about features, usage and development of Midgard, the Open Source Content Management System. See latest Wiki changes.

Installing Midgard

Distribution packages - Midgard installers for distributions like Debian, Fedora and Mac OS X
Source installation - Compile Midgard on any Unix platform
Database setup - Creating a new Midgard database with Datagard
Virtual Host creation - Setting Midgard to answer in different domain names
MidCOM installation - Installing the MidCOM component framework with PEAR
Troubleshooting - Common problems and solutions
Upgrading Midgard - How to upgrade an existing Midgard installation
Authentication settings - Setting Midgard to authenticate using third-party sources like LDAP or Active Directory
Performance tuning - High performance setups with Midgard

Getting started

Midgard Site Wizard - tool for creating new organizations and websites into Midgard
Midgard Wizards - tool for running custom made site wizards plugins
MidCOM content editing - Managing content in Midgard
Groups and People - Managing users in Midgard
Administration interfaces - Applications for managing Midgard

Site building

Style creation - Creating custom layout templates
Dynamic loading - Including content from different site areas into a page
Custom navigation - Using the NAP system to build custom site navigation
Multilingual sites - Making your site support multiple languages
Multilingual sites with MidCOM 2.4 - 2.6 - Older way of making your site support multiple languages
Approvals and scheduling - Adding workflow to your site
Component configuration - Tweaking components of your website
Content schemas - Customizing the fields of your content editors
Error pages - Customizing error pages

Application development

Component development - Developing your own PHP components
Eclipse usage - Using the Eclipse IDE for component development
Coding Standards - Standards for formatting Midgard PHP code
MgdSchema objects - Data handling API
Query Builder - Database object query API
Midgard core in PHP - Midgard core PHP API
Collector - Optimized database query API that doesn't return objects
Datamanager API - Making your content fields customizable
Feed creator - Adding RSS and Atom feeds into your components
Complete API reference
Midgard core C documentation
Midgard in Python - Midgard Python

Midgard concepts

MidCOM - Midgard's Component Framework for PHP
URL handling - How Midgard maps URLs to the database
Permissions - How Midgard handles permissions
Templating Engine - How Midgard's page composition works
Sitegroups - Virtual Hosting Databases in Midgard
Quota - Setting disk quotas in hosting environments
Internationalization - Support for multiple languages and character sets
File attachments - Support for binary files
MgdSchema - Database object abstraction
Metadata object - Centralized metadata system
Formatting engine - Registering and using content formatting functions in HTML
Exorcist - Replication and cross-CMS content migration
UnitTesting - Writing unittests for the php API

Midgard tools and configuration

Command line tools - Running midgard from command line, debug, testing and other tools
Unified configuration - Configuration with ini like files and reusing them between applications

Other information

Glossary - Getting hang of Midgard terminology
Localization - How to translate Midgard to your own language
External tutorials - Midgard information elsewhere on the web
Documentation contribution - How to contribute content to this wiki
Authors - Wiki contributors

The Midgard Wiki software makes it easy for community members to add more documentation to this site. The whole documentation is open content available under the Creative Commons Attribution-ShareAlike license.

Midgard Installation Manual

Tue, 01 Jul 2008 00:42:51 +0000

Midgard installation procedure consists of three stages: installing the framework, setting up a new database with the default applications and creating a new virtual host.

The web site creation process after the installation is not covered in this manual. Please refer to the parts Getting Started with Midgard and Using Midgard CMS in the Midgard documentation.

The framework can be installed from distribution packages or compiled from source. The Midgard team recommends use of the distribution packages wherever they are available for your OS and distribution. The distribution packages are tested to work and therefore very reliable. Also most distributions have automated update methods for packages which ensures you're always using the latest stable version of the Midgard Framework.

The database and virtual host configuration is handled by Datagard, the Midgard database and virtual host administration tool.

Optional installation methods

Setting up Midgard

Upgrading and troubleshooting

Advanced settings

The Midgard documentation team is happy to incorporate your experiences and additions to these installation instructions. To share corrections or platform-specific information, please contact the development team.

Upgrading MidCOM from 2.4 to 2.6

Mon, 02 Jun 2008 20:27:44 +0000

MidCOM upgrade from 2.4 to 2.6 requires several manual steps.

Start the upgrade by backing up your database!

Site initialization

MidCOM 2.6 uses the site initialization system specified in mRFC 0025. This differs quite much from the system used in the old MidCOM template.

Create a new site using the Site Wizard
Go to the site, log in, and click Website -> Website settings
Change the root topic to point to your existing root topic

Content conversion

Deprecated components

Component used in 2.4	Component used in 2.6
de.linkm.taviewer	net.nehmer.static
de.linkm.newsticker	net.nehmer.blog
de.linkm.events	net.nemein.calendar
net.nemein.rss	net.nehmer.blog with RSS subscription mode enabled
midcom.admin.content	Not used, administration is now on-site

Converting the content areas

Run the supplied migrate_26.php script to migrate the content to use MidCOM's new Access Control Lists and new components instead of the old 2.4 ones.

php ./migrate_26.php -c databasename -u admin -p password

Style conversion

Since MidCOM template is not used with MidCOM 2.6, the MidCOM template style elements are not available either. Instead of them utilize direct MidCOM services instead. Some examples below:

Navigation

Use fi.protie.navigation instead of the old <(navi-dynamic)>

Breadcrumb trail

Use something like the following instead of the <(breadcrumb)> element:

<div class="breadcrumb"><?php echo $nap->get_breadcrumb_line(); ?></div>

Example `<(ROOT)>` element

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">  
<html>
    <head>
        <title><(title)> - <?php echo $_MIDCOM->get_context_data(MIDCOM_CONTEXT_PAGETITLE); ?></title>
        <?php
        echo $_MIDCOM->print_head_elements();
        ?>
    </head>
    <body <?php echo $_MIDCOM->print_jsonload(); ?> > 
        <?php
        $_MIDCOM->toolbars->show();
        ?>    
        <(content)>
        <?php
        $_MIDCOM->uimessages->show();
        ?>
    </body>
</html>

Debian

Thu, 29 May 2008 12:57:48 +0000

Add the following lines to /etc/apt/sources.list:

Replace binary-i386 with binary-amd64 for 64bit environments.

For Debian stable ( etch ):

deb http://www.midgard-project.org/debian/dists/stable/main/binary-i386 ./  
# deb-src http://www.midgard-project.org/debian/dists/stable/source/ ./

amd64

deb http://www.midgard-project.org/debian/dists/stable/main/binary-amd64 ./

For Debian testing ( lenny ):

deb http://www.midgard-project.org/debian/dists/testing/main/binary-i386 ./  
# deb-src  http://www.midgard-project.org/debian/dists/testing/source/ ./

For Debian unstable ( sid ):

deb http://www.midgard-project.org/debian/dists/unstable/main/binary-i386 ./  
# deb-src http://www.midgard-project.org/debian/dists/unstable/source/ ./

Run apt-get update for updating the apt database (this adds our repository into your apt).

If you're installing for Apache HTTP Server 1.3.X series, install Midgard with the command:

apt-get install midgard-data php4-midgard.

If you're installing for Apache HTTP Server 2.X series, install Midgard with the command:

apt-get install midgard-data libapache2-mod-midgard

Unfortunatelly there is no empty "midgard" package, as we need to provide support for both Apache HTTP Server series.

Run datagard for setting up a new Midgard database and virtual host. Read the instructions from Setting Up a Midgard Database.

Debian sarge

For old stable debian:

deb http://www.midgard-project.org/debian/dists/sarge/main/binary-i386 ./

Midgard packages for debian sarge include php5-midgard package. This package is built against php5 packages available from http://dotdeb.org. If you want to you PHP5 and php5-midgard on sarge, add dotdeb repository to your sources.list and install php5 and php5-midgard.

For Debian Sarge, you currently have to edit the /etc/apache2/apache2.conf and add:

Include /etc/midgard/apache/httpd.conf

Also you must comment out the Listen 80 entry in /etc/apache2/ports.conf.

If you are running other vhosts on the box, you might have to do more.

If, after following all the instructions regarding the installation with Debian packages, you end up with a broken homepage, try this:

* Try the /aegir/ url (as a suffix to your virtual host URL)
* Check inside the midgard database if you have a host (in the host table) without a prefix (you should, otherwise do the following)
* Restart de datagard application and select Update - Upgrade ...
* If debconf crashes with a geometry error (something about coordinates in the graphical size), resize the window and try again
* Retry using the /aegir/ suffix and use the default admin password "password"

Midgard Apache directives

Thu, 22 May 2008 12:59:42 +0000

Note this list is incomplete for now

MidgardEngine on/off
MidgardDatabase ip/hostname:database user pass
- the IP or hostname of remote database is optional (remember to remove the colon as well)
MidgardBlobDir "path"
MidgardRootfile "path"
MidgardPageCacheDir "path"
- Not to be used with the -nommp variant of MidgardRootFile
MidgardLog level "path"
- if path is empty log goes to apache default error log
- valid levels
  - debug+
MidgardFavorFiles on/off
- If set on then Apache checks if it can serve a file from the DocumentRoot before letting Midgard check for match (and MidCOM sites will always match since they have active url parsing at root page).

MidCOM template style elements

Thu, 22 May 2008 11:32:08 +0000

Here is an example of how the elements can be used in the ROOT element. This example follows the OSCOM XHTML formatting Guidelines, and can be easily used with most layouts as-is, with the actual formatting rules going as CSS to files in the filesystem.

<?php
echo "<?xml version=\"1.0\"?>\n";

// Get the content language
$language = $_MIDCOM->i18n->get_content_language();
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="&(language:h);" lang="&(language:h);">
  <head>
    <title>Site Example | <(page-title)></title>
    <!-- Insert stylesheets and JavaScript files here as example below shows -->
    <link rel="stylesheet" href="/css/style.css" type="text/css" media="screen" />
    <link rel="stylesheet" href="/css/content.css" type="text/css" media="all" />
    <link rel="stylesheet" href="/css/print.css" type="text/css" media="print" />
    <link rel="stylesheet" href="<?php echo MIDCOM_STATIC_URL; ?>midcom.helper.datamanager2/legacy.css" />
    <?php
    // Print MidCOM head elements (e.g. component stylesheets and JavaScript files)
    $_MIDCOM->print_head_elements();
    ?>
  </head>
  <body class="<?php echo $_MIDCOM->metadata->get_page_class(); ?>" <?php $_MIDCOM->print_jsonload(); ?>>
    <?php
    // Show the toolbar
    $_MIDCOM->toolbars->show();
    ?>
    <div id="container">
      <div id="branding">
        <div class="grouplogo">
          <!-- Insert logo here -->
        </div>
        <div id="branding-tagline">
        </div>
        <div id="branding-trail">
          <?php
          $nap = new midcom_helper_nav();
          echo $nap->get_breadcrumb_line();
          ?>
        </div>
      </div>
      <div id="nav">
        <div id="nav-main">
          <?php
          // Load the navigation component
          $_MIDCOM->componentloader->load('fi.protie.navigation');

          // Initialize navigation class
          $navigation = new fi_protie_navigation();

          // Draw the navigation
          $navigation->draw();
          ?>
        </div>
        <div id="nav-language">
         <!-- Language switching links -->
        </div>
        <div id="search">
          <div class="search-input">
          </div>
        </div>
      </div>
      <div id="content">
        <div id="content-main">
          <(content)>
        </div>
      </div>
      <?php
      // Show UI messages
      $_MIDCOM->uimessages->show();
      ?>
      <div id="siteinfo">
        <div id="siteinfo-credits">
          Created by <a href="http://www.nemein.com/">Nemein Oy</a>.
          Powered by <a href="http://www.midgard-project.org/">Midgard CMS</a>.
        </div>
        <div class="siteinfo-legal">
         <!-- Copyright disclaimer and possible licensing -->
        </div>
        <div id="feedback">
            <!-- link to feedback -->
        </div>
      </div>
    </div>
  </body>
</html>

MidCOM component templating

Mon, 19 May 2008 12:51:46 +0000

hi na hi

midgard_replicator method import_from_xml

Fri, 04 Apr 2008 19:37:41 +0000

Imports data from xml content.

void import_from_xml(string xml);

Minimum version: 1.8.1

This method takes one parameter:

xml, valid xml content

You should use:

serialize method if you need serialized object's data.
export_blob method if you need to export midgard_attachment's binary data
export_purged method if you need to export all objects which have previously been purged.

Examples

$xml = file_get_contents("exported.xml");
midgard_replicator::import_from_xml($xml);

PHP midgard_replicator

MgdSchema method connect

Fri, 04 Apr 2008 08:24:21 +0000

__void $object->connect(event_name, array callback, [array params])__

Minimum version: Midgard 1.9

Connects callback to event.

This method takes three arguments:

event_name, a name of the event for which callback is connected to, for example action_update_hook, action_created or action_loaded
callback, an array which is user defined PHP callback
params, an array with parameters which will be passed to callback

A callback function is connected to event(signal) emited by instance which invokes connect method. You may connect to one instance and event as many callbacks as you need.

<?php  

function my_callback($object, $data)
{
    echo "Connected to ".$object->guid;
    echo "And have special data ".$data;   
}

$article = midgard_object_class::factory("midgard_article", 123);
$article->connect("action_update_hook", array("my_callback"), array("abc"));

$article->update();

?>

PHP midgard_connection method connect

Fri, 04 Apr 2008 08:23:30 +0000

Connects a callback.

Name of this method may be confusing, as it may suggest database connection. connect method name is reserved for all midgard objects, and it's related to events handling

Read about mgdschema method connect.

midgard_connection.

PHP midgard_connection method set_debuglevel

Fri, 04 Apr 2008 08:17:49 +0000

Set log verbosity level.

void set_debuglevel(level);

midgard_connection method set_debuglevel takes one parameter and may be called statically.

level string

Available and usable levels:

warn ( or warning)
info
message
debug

The default warn will produce only warning logs. info and message provides functions and method names be written to log file with additional messages produced by invoked functions. debug produces function and method names and all SQL queries.

You may set debuglevel as many time as needed during runtime. Log level is limited to currently invoked application, even if more than one reuse the same configuration and underlying connection to the same database.

This method overwrites loglevel set in unified configuration. Log messages may be written to defined log file.

Example

<?php

 midgard_connection::set_debuglevel("info");

 try
 {
     $object = midgard_person(123);
 }
 catch(midgard_error_exception $e)
 {
     echo "Failed to get object" . $e->getMessage();
 }

 $object->lastname = "Smith";

 midgard_connection::set_debuglevel("debug");

 if(!$object->update()) {

     if(midgard_connection::get_error() = MGD_ERR_ACCESS_DENIED)
         echo "You are not allowed to edit this document"; 
 } 

 midgard_connection::set_debuglevel("warn")

 ?>

midgard_connection.

PHP midgard_connection method get_user

Fri, 04 Apr 2008 08:06:09 +0000

Get midgard_user.

midgard_user get_user(void);

midgard_connection method get_user takes no parameters and may be called statically.

Returns midgard_user object, or NULL if there's no authenticated user.

Read about midgard_user class.

Example

<?php

 $user = midgard_connection::get_user();

 if(!$user->is_admin())
 {
     echo "You are not allowed to edit this document";
 }

 ?>

midgard_connection.

PHP midgard_connection method get_error_string

Fri, 04 Apr 2008 07:59:17 +0000

Get latest error string.

string get_error_string(void);

midgard_connection method get_error_string takes no parameters and may be called statically.

Returns error string.

Example

<?php

 try
 {
     $object = midgard_person(1);
 }
 catch(midgard_error_exception $e)
 {
     echo "Failed to get object" . $e->getMessage();
 }

 $object->lastname = "Smith";

 if(!$object->update()) {

     echo midgard_connection::get_error_string();
 } 

 ?>

midgard_connection.

PHP midgard_connection method get_error

Fri, 04 Apr 2008 07:55:59 +0000

Get latest error id.

int get_error(void);

midgard_connection method get_error takes no parameters and may be called statically.

Returns error constant id.

List or error ids is documented in midgard-core documentation.

Example

<?php

 try
 {
     $object = midgard_person(0);
 }
 catch(midgard_error_exception $e)
 {
     echo "Failed to get object" . $e->getMessage();
 }

 $object->lastname = "Smith";

 if(!$object->update()) {

     if(midgard_connection::get_error() == MGD_ERR_NOT_EXISTS)
         echo "Can not update object which doesn't exist"; 
 } 

 ?>

midgard_connection.

PHP midgard_connection

Fri, 04 Apr 2008 07:44:16 +0000

This part of API is forward compatible and it's recommended for Midgard 1.9/2.0. This is experimental section.

MidgardConnection (midgard_connection) class initializes new Midgard connection and is responsible for holding and setting environmental variables ( like language, sitegroup, errors ). On PHP level is implemented as singleton object, and once connection object is created, it's available as $_MIDGARD_CONNECTION superglobal.

Minimum version: 1.9

Creating new midgard_connection ( constructor )

midgard_connection object is instantiated without arguments.

$cnc = new midgard_connection();

You do not have to store and keep reference to newly created object. Both calls are equal:

$cnc->open("midgard");
$_MIDGARD_CONNECTION->open("midgard");

Midgard Connection methods

PHP midgard_connection method get_lang

Fri, 04 Apr 2008 07:42:58 +0000

Get runtime language.

mixed get_lang(void);

midgard_connection method get_lang takes no parameters and may be called statically.

Returns two letter language code, which confirms ISO 639-1 standard. NULL is returned if runtime language is set to 0 ( no language context ).

Example

<?php

 $lang_code midgard_connection::get_lang();

 if(is_null($lang_code))
 {
     echo "No language set";
 }
 else 
 {
     echo "Language context is {$lang_code}"; 
 } 

 ?>

midgard_connection.

PHP midgard_connection method set_lang

Fri, 04 Apr 2008 07:34:39 +0000

Set runtime language.

boolean set_lang(code);

midgard_connection method set_lang takes one parameter and may be called statically.

language code

Language code should confirm ISO 639-1 standard. Yuo may use built-in midgard_language class to list all available languages and codes.

Returns TRUE if language is changed, FALSE otherwise.

'lang-changed' signal is emitted if language has been changed. You might want to invoke your own callback when connected to $_MIDGARD_CONNECTION.

Example

<?php

 $lang_code = 'pl';
 midgard_connection::set_lang($lang_code);

 ?>

midgard_connection.

PHP midgard_connection method get_sitegroup

Thu, 03 Apr 2008 20:28:20 +0000

Get runtime sitegroup.

mixed get_sitegroup(void);

midgard_connection method get_sitegroup takes no parameters and may be called statically.

Returns the name of the sitegroup for which application's sitegroup context is set. NULL is returned, if runtime sitegroup is 0.

Example

<?php

 $name = midgard_connection::get_sitegroup();

 echo "You are currently working in {$name} sitegroup"

 ?>

midgard_connection.

PHP midgard_connection method set_sitegroup

Thu, 03 Apr 2008 20:22:23 +0000

Set runtime sitegroup.

boolean set_sitegroup(name);

midgard_connection method set_sitegroup takes one parameter and may be called statically.

sitegroup name

Returns TRUE if sitegroup is changed, FALSE otherwise.

'sitegroup-changed' signal is emitted if sitegroup has been changed. You might want to invoke your own callback when connected to $_MIDGARD_CONNECTION.

Example ( using legacy MidgardSitegroup object )

<?php

 $legacy = mgd_get_sitegroup(1);

 midgard_connection::set_sitegroup($legacy->name);

 ?>

midgard_connection.

Roadmap

midgard.admin.sitewizard

Installation

Usage

Site Wizard login link

Create organization with Site Wizard

Create website with Site Wizard

Select style for a Midgard site

Midgard Documentation

Installing Midgard

Getting started

Site building

Application development

Midgard concepts

Midgard tools and configuration

Other information

Midgard Installation Manual

Optional installation methods

Setting up Midgard

Upgrading and troubleshooting

Advanced settings

Upgrading MidCOM from 2.4 to 2.6

Site initialization

Content conversion

Deprecated components

Converting the content areas

Style conversion

Navigation

Breadcrumb trail

Example <(ROOT)> element

Debian

Debian sarge

Midgard Apache directives

MidCOM template style elements

MidCOM component templating

midgard_replicator method import_from_xml

Examples

MgdSchema method connect

PHP midgard_connection method connect

PHP midgard_connection method set_debuglevel

Example

PHP midgard_connection method get_user

Example

PHP midgard_connection method get_error_string

Example

PHP midgard_connection method get_error

Example

PHP midgard_connection

Creating new midgard_connection ( constructor )

Midgard Connection methods

PHP midgard_connection method get_lang

Example

PHP midgard_connection method set_lang

Example

PHP midgard_connection method get_sitegroup

Example

PHP midgard_connection method set_sitegroup

Example ( using legacy MidgardSitegroup object )

Example `<(ROOT)>` element