Documentation

MidgardAttachment

Michel Gaudry — Fri, 27 May 2011 12:52:56 +0000

Attachments, also known as blobs, can be used to administer and serve out arbitrary data with Midgard. This will typically be used for images, sounds, flash movies, etc. and for files available for download.

Attachments can be connected to any kind of resource, and attachments to page records will be served out directly based on their name.

Attachment methods and functions

$object->createattachment - Create an attachment record
$object->deleteattachment - Delete an attachment record
$object->getattachment - Instantinate an attachment object
$object->listattachments - List object's attachments
$object->updateattachment - Update an attachment record
$object->openattachment - Open file handle to the attachment
$object->serveattachment - Serve attachment contents
mgd_stat_attachment

Deprecated attachment functions

mgd_delete_attachment
mgd_get_attachment
mgd_update_attachment
mgd_open_attachment
mgd_serve_attachment

Site building with MidCOM

popeyevn popeyevn — Mon, 02 May 2011 04:18:24 +0000

MidCOM is the default way to build websites with Midgard CMS. Here is a collection of tutorials on how to make functional and usable sites with the framework.

The basic idea with MidCOM is that the site is built out of a set of existing site features, or components. Each folder on the site is assigned a component that manages it, making some folders event calendars, news listings or something else.

Layout and navigation

Style creation - Creating custom layout templates
Making and modifying styles
Dynamic loading - Including content from different site areas into a page
MidCOM template style elements - the default style elements provided
Custom navigation - Using the NAP system to build custom site navigation
Error pages - Customizing error pages
Browser detection with midcom
The default Midcom CSS elements
Modifying MidCOM component output

Content and structure

Multilingual sites - Making your site support multiple languages
Component configuration - Tweaking components of your website
Content schemas - Customizing the fields of your content editors
TinyMCE editor - Customizing the buttons of TinyMCE editor window
Using Aegir image pop-up with MidCOM
How to set up site search using Solr

Permissions and workflow

Permissions in Midgard - Groups and ownerships
Approvals and scheduling - Adding workflow to your site
Creating groups and users

You may also find a lot of interesting information within Nathan Syntronics MidCOM pages.

In addition to using the existing components, you can also develop your own.

MidCOM template

popeyevn popeyevn — Mon, 02 May 2011 04:17:00 +0000

MidCOM template is a Midgard page template shipping with MidCOM. It is used for loading, configuring and running the MidCOM environment in a Midgard-powered website.

When you create a site using the Midgard Site Wizard, it will be automatically set up using the MidCOM template.

The MidCOM template is provided as a Repligard XML package named midcom-template.xml that can be installed via datagard.

Documentation:

midcom.services.rcs

Alexander Schuster — Mon, 18 Apr 2011 12:56:15 +0000

MidCOM Revision Control Service (RCS)

This applies to MidCOM version 2.6 and upwards.

The MidCOM RCS is backwards compatible with the older revision control service found in Aegir and also supported by MidCOM Datamanager, however to user the new revision control service, you will have to enable it spesificly in your MidCOM configuration file (usually found in /etc/midgard/midcom.conf).

The simpliest way to do this is to use the autoconf.php file found in the MidCOM support directory. For PEAR installed versions of MidCOM look in the /usr/share/php/midcom/support/midcom/support/ directory for this file.

Just run php autoconf.php and it will generate a suggested configuration for you.

A note on the `/var/lib/midgard/rcs` directory

It seems that Datagard creates this directory for you, but with the wrong file permissions. Therefore you should check this and make sure that the Apache user can write to the directory.

Also, if you are running several Midgard databases you should use different root directories for each database.

Configuration options

There are three configuration options that may be used with the RCS service:

midcom_services_rcs_bin_dir: the prefix for the RCS utilities (usually /usr/bin)
midcom_services_rcs_root: the directory where the RCS files get placed. Usually /var/lib/midgard/rcs.
midcom_services_rcs_use: If set to true, MidCOM will fail hard if the RCS service is not operational. It is useful to ensure that the service is working.

Mac OS X

Anna Wasinska — Thu, 03 Mar 2011 19:29:55 +0000

Midgard for MacPorts

Midgard is being maintained as part of the MacPorts collection. MacPorts is a Mac version of the BSD Ports collection that enables easy installation of preconfigured source packages. More information about MacPorts is available in their wiki.

To install Midgard with MacPorts you need the Apple Xcode Tools. Once you have both MacPorts and Xcode installed, open Terminal and run:

$ sudo port sync
$ sudo port install apache2
$ sudo port install mysql5 +server
$ sudo port install php5 +apache2 +pear +mysql5
$ sudo port install midgard-data

Then you need to initialize and start the MySQL and Apache processes:

$ sudo launchctl load -w /Library/LaunchDaemons/org.darwinports.mysql5.plist
$ sudo launchctl load -w /Library/LaunchDaemons/org.darwinports.apache2.plist

After that you should be able to set up the database and virtual host normally.

As these instructions are not very complete, feel free to ask Jyrki Wahlstedt (jwa (at) macports (dot) org).

Formatting engine

Andreas Flack — Sat, 22 Jan 2011 19:38:18 +0000

Inline variable display

Midgard adds a new language construct to PHP which allows you to include the value of a variable in HTML without using a <? echo $var; ?> construct.

You can now simply use &(variablename); directly in HTML. Note the absence of the $.

Object variables that would normally be accessed in PHP code as $object->field can be inserted as &(object.field);. Similarly, fields of an associative array can be inserted with &(array['key']);.

Standard formatting modifiers

The way the value is formatted can be specified by adding a modifier after the variable name: &(variable:modifier);.

In PHP code the modifiers can be executed using the mgd_format function.

The standard modifiers are:

`h` - Encode content as HTML

Add value as HTML. Escapes & to &, < to < and > to >.

Everything between [< and >] is added verbatim with the [< and >] dropped. PHP code embedded in such a section is executed.

`H` - Encode content as HTML but keep entities verbatim

Add value as HTML. Everything is included verbatim.

`f` - Format plain text to HTML

Add value as formatted text, the plain text input is formatted as HTML on the fly.

Lines starting with `` will be transformed to unnumbered lists.

Paragraphs delimited by an empty line will be surrounded by <p> and </p>.

Everything between [< and >] is added verbatim with the [< and >] dropped.

Note: PHP code embedded in such a section is executed. If you want to enable safe content input from unsecure users, use the Markdown datatype instead.

`F` - Format plain text to HTML with headlines

Add value as formatted text, the plain text input is formatted as HTML on the fly.

Lines starting with `` will be transformed to unnumbered lists.

Paragraphs delimited by an empty line will be surrounded by <p> and </p>.

Lines after an empty line with less than 10 words that do not end in a period are formatted as <h2>.

Everything between [< and >] is added verbatim with the [< and >] dropped.

Note: PHP code embedded in such a section is executed. If you want to enable safe content input from unsecure users, use the Markdown datatype instead.

`p` - Execute content as PHP code

Execute a value as PHP. Executes the value of the variable.

`u` - URL encode content

Add the value urlencoded. Replaces non-safe URI characters with their %code equivalents.

`s` - Show content as-is

Show variable unmodified.

Custom formatters

You can also add custom formatters to your Midgard application. This is a powerful way of extending Midgards formatting engine.

Basically you write a function which gets the text-to-be-formatted as an argument and echos dumps the formatted output to stdout.

You then register that function using to Midgard's formatting engine using the mgd_register_filter function.

Example:

function midgardize_my_content($text) 
{  
    // Replace all instances of "CMS" in content with "Midgard"
    $formatted_text = str_replace('CMS', 'Midgard', $text);
    echo $formatted_text;  
}  

mgd_register_filter('mgd', 'midgardize_my_content');

// Then, in some style element you can do this: &(my_variable:xmgd);

The custom formatters are prefixed with `x` before the registered name (in this case `mgd`)

org.routamc.photostream

Alexander Schuster — Wed, 22 Sep 2010 14:30:44 +0000

org.routamc.hotostream is a component for uploading, sorting, tagging and managing your pictures.

Uploading pictures: although not visible at first hand, you can upload an archive with pictures (gz, zip). You can assign a title to your pictures which is assigned to every picture in an archive
Tagging pictures: assigning tags to your pictures is the best way to sort and filter your pictures in galleries later, when uploading an archive all pictures get assigned the same tags (tags should be separated by a whitespace, not komma!)

openSUSE and SLE

Jarkko Ala-Louvesniemi — Mon, 12 Jul 2010 11:48:57 +0000

OpenSUSE and SLES/SLED packages are available (among other distributions) on openSUSE Build Service.

Note: Please note that the default rpm installation of Midgard requires that you have enabled server:php:extensions.

After you've installed the rpm packages, proceed by running the Datagard install action which sets up Midgard CMS for you:

datagard -a install

More information about Midgard installation in general is available in the Midgard Installation Manual.

MidgardQueryBuilder Complex Constraints

Rex van Dorp — Tue, 04 May 2010 11:52:22 +0000

A special dot '.' separator may be used for add_constraint and add_order MidgardQueryBuilder methods. The main purpose of the dot separator is to query metadata and referenced types defined as properties' link in the MgdSchema files.

The basic syntax for constraints and dot separator is:

propertyA.propertyB

propertyA is a member of a class which was initialized with Midgard Query Builder. propertyB is a member of a class which was defined as "linked" one in Midgard schema file.

There are few exceptions ( reserved words ) for propertyA name :

metadata

add_constraint("metadata.created", ">" , "2006-01-27 00:00:00");
parameter

add_constraint("parameter.name", "=" , "component");
attachment

add_constraint("attachment.mimetype", "LIKE" , "jpg");

Metadata query example

An example for $article->name and $article->metadata->created constraints:

<?php
$qb = new MidgardQueryBuilder("midgard_article");

$qb->add_constraint("metadata.created", ">" , "2006-01-27 00:00:00");
$qb->add_constraint("name", "=", "index");

$returned_array = $qb->execute();

?>

Only those objects will be queried which name is 'index' and were created after January 27th, 2006.

Referenced type query example

Schema type example for referenced types.

<type name="midgard_article" table="article">
        <property name="creator" link="midgard_person:id"/>
</type>

PHP example

<?php
$qb = new MidgardQueryBuilder("midgard_article");

$qb->add_constraint("creator.username", "LIKE" , "%john%");
$qb->add_constraint("name", "=", "index");

$returned_array = $qb->execute();

?>

Only those objects will be queried which name is 'index' and referenced object's username property contains 'john'.

midgard\_article's creator property value must be equal to midgard\_person's id property's value and midgard_person's username property value must contain 'john'

Mixed complex query example

Schema definition:

 <type name="midgard_member" table="member" parentfield="">
    <property name="id"       type="integer" primaryfield="id"/>
    <property name="extra"    type="string"/>
    <property name="uid"      type="integer" link="midgard_person:id"/>
    <property name="gid"      type="integer" link="midgard_group:id" />
 </type>

<?php
$qb = new midgardquerybuilder("midgard_member");
$qb->add_constraint('gid.name', '=', "Users group");
$qb->add_constraint('metadata.created', '>', "2006-02-27 18:45:00");
$qb->add_order('uid.firstname');

$returned_array = $qb->execute();
?>

Such query returns objects for those persons who are members of "User group" group, and were created after 27th February, 2006. Returned array is sorted by firstname of person record.

Parameter example

PHP example

<?php
$qb = new midgard_query_builder('midgard_article');

$qb->add_constraint('parameter.domain', '=', 'domain');
$qb->add_constraint('parameter.name', '=', 'name');
$qb->add_constraint('parameter.value', '=', 'value');

$result = $qb->execute();
?>

This code will search for the parameter domain.name with the given value and will return every article with that parameter and value.

MidgardQueryBuilder

Rex van Dorp — Tue, 04 May 2010 11:40:00 +0000

Midgard Query Builder is a special Midgard PHP class which enables developers to optimize SQL queries used in a Midgard application. Query Builder (QB) may be used only with MgdSchema registered types.

Creating new Query Builder object instance

Query Builder is instantiated by giving it the name of the MgdSchema type being queried.

__object midgard_query_builder(string 'MgdSchema class');__

Midgard Query Builder methods

Usage example:

<?php
// Instantiate Query Builder for an Article object
$qb = new midgard_query_builder('midgard_article');

// List articles only in topic 123
$qb->add_constraint('topic', '=', 123);

// Run the query
$articles = $qb->execute();

// Show the articles
foreach ($articles as $article)
{
    echo "<h2>{$articles->title}</h2>\n";
}
?>

MidgardQueryBuilder Objects and Parameters

Rex van Dorp — Tue, 04 May 2010 11:33:36 +0000

midgard_query_builder class is very usefull to fetch object's data from database, but it's a bit limited if you need to query object and its parameters.

Basically, during your development work, you have two cases to fetch object specifing parameters constraints. The first case is the simplest, when you need to query object and only one parameter's constraint should be used. The second is much more difficult, when you need to query object and more than one parameter's constraint should be defined. In this case workaround is needed.

Those two examples should explain how to write code for both cases:

Query object with one parameter.

$qb = new midgard_query_builder("midgard_article");
$qb->add_constraint("name", "=", "news");
$qb->add_constraint("parameter.value", "=", "cool"); 
$ret = $qb->execute();

$my_object =& $ret0

Query object with more than one parameter's constraint.

$qb = new midgard_query_builder("midgard_parameter");
$qb->add_constraint("domain", "=", "midcom");
$qb->add_constraint("name", "=", "component");
$qb->add_constraint("value", "=", "my_component");
$ret = $qb->execute();

$my_object = new midgard_topic($ret0>parentguid);

Note that we initialized QB instance for midgard_parameter, not for objec's class we wanted to fetch. This cases requires two queries instead of one, but unfortunatelly midgard_query_builder is not aware ( and can not guess ) if you defined constraint in the same table's scope or another one ( which might be tha same ) for which SQL join should be made.

In latter example, one object has been instatiated. But of course , you may need less constraints if you need fetch more objects:

$qb = new midgard_query_builder("midgard_parameter");
$qb->add_constraint("domain", "=", "midcom");
$ret = $qb->execute();

foreach($ret as $obj) {
    $my_object = new midgard_topic($obj->parentguid);
    echo "Found {$my_object->name}";
}

midcom.services.indexer

Arttu Manninen — Mon, 19 Apr 2010 20:53:28 +0000

midcom.services.indexer is the integrated full-text search system in MidCOM. It utilizes the Apache Lucene for actual search capabilities.

This is very old information, see How to set up site search using Solr instead

Installing MidCOM indexer

See the midcom.services.indexer installation document.

Configuring the MidCOM Indexer Daemon (Quick start guide)

The MidCOM index daemon takes an optional filename as an argument during startup. It allows you to control four parameters: IP and port to bind to, log file name and log level. We are using standard Java Property files here, which consist of name = value pairs.

So a debug.conf example config file could look like this:

logfile = debug.log
loglevel = FINEST

which would be used like this:

java -jar indexer.jar debug.conf

`bind` and `port`

These two parameters control where the daemon binds to. By default bind is set to 127.0.0.1 and port to 2222, which matches the MidCOM default configuration and is thus fine if you are working in the default installation environment.

`logfile`

This parameter defaults to stderr which, naturally, logs to the stderr pipe the daemon launches with. You can set any valid filename here, of course we need write permission.

Log files are limited to 5 MB in size and are automatically rotated 4 times.

`loglevel`

Specifies what to log, we use the log levels defined in the Java package java.util.logging.Level here, defaulting to WARNING. Valid log levels, from most terse to most verbose:

SEVERE
WARNING
INFO
CONFIG
FINE
FINER
FINEST

Note, that not all of these log levels are in use yet, so don't wonder if you have no differences when moving between adjecant log levels.

WARNING is recommended for day-to-day operation, FINEST for debugging only. If you want to log each connection attempt, use INFO.

midcom.services.indexer installation

Arttu Manninen — Mon, 19 Apr 2010 20:52:57 +0000

These are instructions for installing and setting up the MidCOM full-text search system.

This is very old information, see How to set up site search using Solr instead

General Structure

The Indexer is not directly indetrated into PHP. On one hand, the performance in a persistently running indexer daemon is (on average) better, than a fully integrated solution. On the other hand, there is just no really usable PHP-level On-Demand Indexer out there anyway (not that I would trust PHP far enough in this respect.

The structure of the index is further described in the mRFC 9. See there how Documents and Fields interact.

This document will focus on setting up and using the Indexer.

Setting up the Lucene Daemon

All required files of the current CVS state are available for Download on the required indexer files page, but if you want an up-to-date build of the system, follow these instructions:

Building and Installing the Daemon

Go to the Lucene Website and download the latest Lucene binary tarball. In it you will find a file named lucene-$version.jar. Rename it to a plain lucene.jar. (Use version 1.4.3 found here http://apache.fi/lucene/java/archive/)
Go to the external-tools/indexer-backends/lucene directory of the current MidCOM CVS. Copy the lucene.jar file into this directory and run make there, it will build a file named indexer.jar.
Create a directory and copy the files lucene.jar, indexer.jar, xml-communication-request.dtd and xml-communication-response.dtd into it.

Running the Daemon

Go to the newly created directory, with an user account that has write permissions to this directory. Run:

/usr/bin/java -jar indexer.jar (or wherever you have java)

You should be fine from that point, the daemon will listen to 127.0.0.1:2222, which is the default setting from the MidCOM side too.

The Daemon will run in foreground by default, unless you launch it with some nohup wrapper. For the init-script (for debian), see "To make indexer run as a init.d script" section at the bottom of this page.

Changing Configuration

The daemon will take a filename during startup as first command line argument. A full configuration file looks like this:

logfile = 
loglevel = WARNING
bind = 127.0.0.1
port = 2222

What I wrote here are the defaults, log warning level messages to stderr (no log file) and bind to 127.0.0.1:2222. Check java.util.logging.Level for valid logging levels.

You should be fine using the defaults though.

Configuring MidCOM to use the Indexer

This is relativly easy, and consists of three tasks:

Activate the indexing feature in the MidCOM configuration

As usual, you will find all detailed information in the MidCOM API docs, section midcom_config.php. As long as you stick to the default configuration, it is enough to activate the XMLTCP indexing backend during MidCOM startup:

$GLOBALS['midcom_local_config']['indexer_backend'] = 'xmltcp';

Two more configuration options, indexer_xmltcp_host and indexer_xmltcp_port, allowing you to explicitly specify the host/port combination where the indexer runs.

Index your entire site

Unless you are building a site from scratch, you obviously have to reindex your entire website. This is done by accessing this URL with full admin privileges:

http://your.site.com/midcom-exec-midcom/reindex.php

Two important notes about this: First it will take quite some time, as the MidCOM side of the interface does not yet support batch indexing. Second, and far more important, Reindexing will take a huge amount of RAM. For example, a site with around 250 documents on it requires about 60 MB of total RAM.

Create the Indexer Frontend

Create a new topic using the component midcom.helper.search.

To make indexer run as a init.d script (on debian).

To make indexer run as a init.d script so you can use normal start & stop do the following steps. This is for Debian system. Tested in Sarge. You must perform these steps as root.

Create /usr/share/midgard/indexer/indexer in which you put the following code:

#! /bin/sh
#
# indexer

set -e

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DESC="MidCOM indexer"
NAME=java-indexer
DAEMON=/usr/share/midgard/indexer/$NAME
PIDFILE=/var/run/$NAME.pid
SCRIPTNAME=/etc/init.d/$NAME
ARGS="-jar indexer.jar"
APPDIR=/usr/share/midgard/indexer

# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0

# Read config file if it is present.
#if <span class="wiki_missing_nouser" title="Login to create this missing page"> -r /etc/default/$NAME </span>
#then
#   . /etc/default/$NAME
#fi

#
#   Function that starts the daemon/service.
#
d_start() {
    start-stop-daemon --start --make-pidfile --pidfile $PIDFILE \
        --chdir $APPDIR --background --quiet \
        --exec $DAEMON -- $ARGS
}

#
#   Function that stops the daemon/service.
#
d_stop() {
    start-stop-daemon --stop --quiet --pidfile $PIDFILE
}

#
#   Function that sends a SIGHUP to the daemon/service.
#
d_reload() {
    start-stop-daemon --stop --quiet --pidfile $PIDFILE --signal 1
}

case "$1" in
  start)
    echo -n "Starting $DESC: $NAME"
    d_start
    echo "."
    ;;
  stop)
    echo -n "Stopping $DESC: $NAME"
    d_stop
    echo "."
    ;;
  #reload)
    #
    #   If the daemon can reload its configuration without
    #   restarting (for example, when it is sent a SIGHUP),
    #   then implement that here.
    #
    #   If the daemon responds to changes in its config file
    #   directly anyway, make this an "exit 0".
    #
    # echo -n "Reloading $DESC configuration..."
    # d_reload
    # echo "done."
  #;;
  restart|force-reload)
    #
    #   If the "reload" option is implemented, move the "force-reload"
    #   option to the "reload" entry above. If not, "force-reload" is
    #   just the same as "restart".
    #
    echo -n "Restarting $DESC: $NAME"
    d_stop
    sleep 1
    d_start
    echo "."
    ;;
  *)
    # echo "Usage: $SCRIPTNAME {start|stop|restart|reload|force-reload}" >&2
    echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2
    exit 1
    ;;
esac

exit 0

If you do not already have PEAR XML_Parser, you need to also get that:

pear install xml_parser

Copy indexer.jar, xml-communication-request.dtd, xml-communication-response.dtd, lucene.jar in /usr/share/midgard/indexer/

Make sure you have Java runtime installed. Create symlink so that /usr/share/midgard/indexer/java-indexer points to java.

ln -s /opt/j2re/bin/java /usr/share/midgard/indexer/java-indexer

The process we will be running will then be called java-indexer so this wont mess up with other java processes.

Create symlink:

ln -s /usr/share/midgard/indexer/indexer /etc/init.d/indexer

To make it automatically start and stop on startup/shutdown:

update-rc.d indexer defaults

Have fun indexing!

Drupal

Alexey Zakhlestin — Wed, 31 Mar 2010 14:11:43 +0000

Preface

This instruction supposes that you are installing MidCOM website in a subdomain of Drupal website and that MidCOM has access to Drupal's host filesystem and database. For example: Drupal at example.com and MidCOM at midcom.example.com. It is possible to achieve similar results in other environments, but process would become a bit more complicated

Drupal side

install "erl" (External Redirector after Login) module available from github repo
enable "erl" module from Drupal's administration UI. It will register erl/login, erl/logout and erl/return URLs
in "erl" module's settings add MidCOM's hostname to the list of allowed domains.

MidCOM side

make sure, that php's pdo_mysql extension is enabled (or pdo_pgsql, if Drupal uses PostgreSQL database)
install "net.nemein.drupalauth" component from midgard's svn repo (8.09.8.25504+)
make sure, that midcom.core's version is 8.09.8.25505 or newer (update if necessary)
in MidCOM's website-settings (available via Asgard) set 3 config-variables:
- Path to Drupal's settings.php file => "/usr/share/drupal6/sites/default/settings.php" (set whatever is right for your setup)
- Drupal's domain => "example.com" (according to our imaginary setup, set real domain of your Drupal host)
- Enable authentication via Drupal => "Yes"

Done. As soon as you press "Save" button MidCOM won't allow you to authenticate using midgard logins/passwords anymore. You will need to use Drupal's credentials.

Hint: create "admin" account in Drupal. It will connect to midgard's "admin" account and you will be able to proceed with this instruction

Edit your MidCOM styles to have the following links:

http://example.com/?q=erl/login for "Login" link (remember to replace "example.com" with your Drupal's site hostname)
http://example.com/?q=erl/logout for "Logout" link
http://example.com/?q=user/register for "Register" link
http://example.com/?q=user for "My Account" link

check how we did it for meego.com demo-site here

Midgard Documentation

Alexey Zakhlestin — Wed, 31 Mar 2010 13:37:31 +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/EL, openSUSE/SLE, Ubuntu 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

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
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
Drupal integration - Using Drupal sessions for authenticating MidCOM

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 in ObjectiveC - Midgard in ObjectiveC and on the Mac
Midgard App Builder - Midgard package for building Fluid applications.

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 Wizards - tool for creating new organizations and websites into Midgard

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
Folklore - Cultural points about the Midgard project

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.

How to set up site search using Solr

Eero af Heurlin — Tue, 23 Feb 2010 13:53:10 +0000

About Solr

Solr is an open source enterprise search server based on the Lucene Java search library, with XML/HTTP and JSON APIs, hit highlighting, faceted search, caching, replication, and a web administration interface. It runs in a Java servlet container such as Tomcat.

That means that to use Solr you will need to run in some Java servlet container.

Using solr-tomcat5.5

On Ubuntu et co we have this package available and dependency of the midgard metapackage, so after installing just do the following:

Make sure the Catalina process uses UTF-8 for URI parsing
Download the MidCOM Solr Schema and copy over /etc/solr/conf/schema.xml

Configure your website to use the indexer Set the following values in code-init-before-midcom:

$GLOBALS['midcom_config_local']['indexer_reindex_allowed_ips'] = array ( '127.0.0.1', 'server.main.ip' );
$GLOBALS['midcom_config_local']['indexer_backend'] = 'solr';
$GLOBALS['midcom_config_local']['indexer_xmltcp_host'] = 'localhost';
$GLOBALS['midcom_config_local']['indexer_xmltcp_port'] = '8180';

If you get java.lang.NoClassDefFoundError in Tomcat logs you may need to disable Tomcat security

Using Jetty

This section is very old, we suggest using Tomcat

Dependencies

On Debian you need the following packages:

apt-get install libmx4j-java libregexp-java libsablevm-classlib1-java libservlet2.4-java libtomcat5.5-java libxerces2-java sun-java5-jdk

Installing Jetty

Solr comes with Jetty in the example directory.

Installing Solr

You must use version 1.1 of Solr

Download Solr from the Solr website http://www.apache.org/dyn/closer.cgi/lucene/solr/
Unpack solr and copy the jetty example install to the jetty home.

unzip apache-solr-1.1*.zip
cp -R apache-solr-1.1*/example /usr/share/jetty
Download the setupfiles for Solr. (Currently just for Debian)

svn co https://svn.midgard-project.org/midgard/trunk/external-tools/indexer-backends/solr
cd solr
bash ./install-solr.sh

This will install setupfiles in the correct places and set the correct permissions.

Start solr

/etc/init.d/jetty start

Now solr is running and listening to requests on port 8983.

Create a topic with the Search component.
In the menu, choose website -> website configuration.
Set the following values:

Indexer: Solr
Hostname of indexer xmltcp service: localhost (or the host solr is running on)
Port of indexer xmltcp service: 8983

Reindex your site. Visit /midcom-exec-midcom/reindex.php. This will take some time.
You should now be able to run searches on your site.

Security

In the addListener definition in jetty.xml, add the following:

<Set name="Host">localhost</Set>

So Jetty doesn't listen to requests from the outside. If you want to still access the admin interface, use firewall scripts to hide the port from most users.

See http://wiki.apache.org/solr/SolrSecurity for more information.

Troubleshooting

"Authorization required"

When you're running midcom-exec-midcom/reindex.php, and you get "Authorization required" errors, you should modify the indexer_reindex_allowed_ips. Either set it in /etc/midgard/midcom.conf or in the host settings.

For the midcom.conf file, you need to add:

$GLOBALS['midcom_config_site']['indexer_reindex_allowed_ips'] = array('127.0.0.1','192.168.126.128','127.0.1.1');

"Indexer failed"

If you get an "indexer failed" error when reindexing the site, ensure that SOLR's data directory exists and is writable:

mkdir /usr/share/jetty/solr/data  
chown jetty /usr/share/jetty/solr/data

External tutorials

Mattias Stahre — Mon, 22 Feb 2010 01:27:06 +0000

IBM DeveloperWorks Tutorial
A nice tutorial on Midgard. Written by David Seager, a software engineer at IBM, the article describes setting up a basic Midgard site. The article also does a good job of setting up a general context for what Midgard is and how it works.
http://www-106.ibm.com/developerworks/library/w-midgard/

New Architect on Midgard
The May 2000 issue of New Architect (then Web Techniques) carried an introductory article and tutorial to Midgard by Brian Jepson.
http://www.webtechniques.com/archives/2000/05/jepson/

Midgard tutorial in German
3rd Evolution's tutorial on Midgard and Nadmin Studio on Mandrake Linux. In German.
http://www.3rd-evolution.de/docs/misc/midgard/

Reference manuals

PHP Manual
The PHP programming language manual and API reference.
http://www.php.net/manual/

MidgardWiki @ Content Control
Wiki collecting Midgard site building information.

PHP midgard object method delete_attachments

Tero Heikkinen — Fri, 19 Feb 2010 14:08:14 +0000

Delete object's attachments.

boolean delete_attachments(array args);

This method takes one argument:

args, associative array

Array's keys must be midgard_attachment properties' names, values should define constraints with properties's values.

Delete all attachments with matching properties' values. It's possible to undelete attachment which have been deleted with this method.

Blobs that are linked to attachment are not deleted because one blob can be linked to many attachments. Blobs are deleted with blob's remove_file function

Returns TRUE on success, FALSE otherwise.

Example

<?php

/* Delete all image attachments */

 try {
     $style = new midgard_style($guid);
 } catch (Exception $e) {
     echo $e->getMessage();  
 }

 $args = array ("mimetype" => "image/jpeg");

 if($style->delete_attachments($args))
     echo "Deleted all image attachments";

 ?>

midgard object attachments

Debian

Jarkko Ala-Louvesniemi — Thu, 04 Feb 2010 11:19:33 +0000

Debian packages are now built using OpenSuse Build System.

Add OBS repository to /etc/apt/sources.list:

deb http://download.opensuse.org/repositories/home:/midgardproject:/ragnaroek/Debian_5.0/ ./

Or for Debian Etch:

deb http://download.opensuse.org/repositories/home:/midgardproject:/ragnaroek/Debian_Etch/ ./

To get rid of this:

W: GPG error: http://download.opensuse.org ./ Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY DFD08130B9E2252E

...Download Release.key and import it, e.g.:

wget http://download.opensuse.org/repositories/home:/midgardproject:/ragnaroek/Debian_5.0/Release.key

cat Release.key | apt-key add -

Download packages and install them manually, if packages can not be installed with apt-get.

Run these commands when repository is added:

apt-get update
apt-get install midgard

Try to install midgard-debian package if midgard is not installable.

If latter fails:

apt-get install midgard-data php5-midgard

Old stable 1.8 generation "Thor":

deb http://download.opensuse.org/repositories/home:/midgardproject:/midgard18/Debian_Etch/ ./

Kerberos single sign-on with Active Directory

Eero af Heurlin — Thu, 21 Jan 2010 12:33:36 +0000

Kerberos authentication is a third party authentication mechanism supported by Midgard. It allows users to log in to Midgard using their LDAP or Active Directory accounts. In Kerberos authentication users may log in to Midgard in the normal way or using single sign-on method.

Basic kerberos configuration on midgard server

Install mod_auth_kerb.

Configure /etc/krb5.conf

[libdefaults]
    default_realm = KERBEROS.REALM

[domain_realm]
    apache.server.fqdn = KERBEROS.REALM

[realms]
    KERBEROS.REALM = {
        kdc = kdc.kerberos.realm
        }

Test configuration

$ kinit username
$ klist

If you get ticket from the kerberos server, you should be fine to continue. Otherwise you might find the troubleshooting section, in the end of this document, useful.

Creating keytab for single sign-on

First you must create a user account on the kerberos domain controller server. The user account must not be disabled and the password must stay the same. Otherwise you might need to recreate the keytab. In this example the user account name is "apache_server" and has password "apache_password".

Windows Server 2003:

C:\Program Files\Support Tools>ktpass -princ HTTP/apache.server.fqdn@KERBEROS.REALM -mapuser apache_server -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass apache_password -out name.keytab

Windows Server 2000 (not tested):

C:\Program Files\Support Tools>ktpass -princ HTTP/apache.server.fqdn@KERBEROS.REALM -mapuser dummyuser -crypto DES-CBC-MD5 -pass password -out name.keytab

Install support tools to optain ktpass.exe. After creating the keytab you propably need to reset the password because of the new crypto type. You need to use the same password.

apache.server.fqdn = the site url you are going to use. The url must be resolvable by the kerberos and midgard server to the midgard server ip-address.

Place the keytab file on the midgard server and give apache user read rights to the file.

Test the keytab:

$ kinit -k -t /etc/name.keytab HTTP/apache.server.fqdn
$ klist

If you get ticket from the kerberos server, you should be fine to continue. Otherwise you might find the troubleshooting section, in the end of this document, useful.

Configuring midgard vhost

Below is a configuration for a kerberos SingleSignOn authentication which fallbacks to a kerberos password authentication.

Servername apache.server.fqdn
MidgardAuthType trusted

<Location "/">
    AuthName "Kerberos Authentication"
    AuthType Kerberos
    KrbAuthRealms KERBEROS.REALM
    Krb5Keytab /etc/name.keytab
    KrbMethodNegotiate on
    KrbMethodK5Passwd on
    Order Allow,Deny
    # Allow cron scripts etc from local machine
    Allow from localhost
    Allow from apache.server.fqdn
    # Require kerberos for others
    Require valid-user
    Satisfy any
</Location>

Browser support for single sign-on

Firefox:

Go to about:config edit network.negotiate-auth.trusted-uris and add http(s)://(site)

IE6:

Add the site to trusted sites. Make sure that "Enable Integrated Windows Authentication" is on

Troubleshooting and useful links

In midgard server the site url must be /etc/hosts as a first entry for the ip in question:

172.0.0.1       locahost.localdomain localhost
'ip-address'    apache.server.fqdn apache

The midgard server must be in same time with the kerberos server. You can use ntp or ntpdate for this.

GSS failure "Key version number for principal in key table is incorrect"

If you reset the password after creating the keytab you will need to create a new one, even if kinit does not complain the Kerberos server will refuse to serve authentication requests for the "old" keytab.

Links:

Documentation

MidgardAttachment

Attachment methods and functions

Deprecated attachment functions

Site building with MidCOM

Layout and navigation

Content and structure

Permissions and workflow

MidCOM template

Documentation:

midcom.services.rcs

MidCOM Revision Control Service (RCS)

A note on the /var/lib/midgard/rcs directory

Configuration options

Mac OS X

Midgard for MacPorts

Formatting engine

Inline variable display

Standard formatting modifiers

h - Encode content as HTML

H - Encode content as HTML but keep entities verbatim

f - Format plain text to HTML

F - Format plain text to HTML with headlines

p - Execute content as PHP code

u - URL encode content

s - Show content as-is

Custom formatters

Example:

org.routamc.photostream

openSUSE and SLE

MidgardQueryBuilder Complex Constraints

Metadata query example

Referenced type query example

Mixed complex query example

Parameter example

See also

MidgardQueryBuilder

Creating new Query Builder object instance

Midgard Query Builder methods

Usage example:

See also

MidgardQueryBuilder Objects and Parameters

Query object with one parameter.

Query object with more than one parameter's constraint.

midcom.services.indexer

Installing MidCOM indexer

Configuring the MidCOM Indexer Daemon (Quick start guide)

bind and port

logfile

loglevel

midcom.services.indexer installation

Recommended Reading

General Structure

Setting up the Lucene Daemon

Building and Installing the Daemon

Running the Daemon

Changing Configuration

Configuring MidCOM to use the Indexer

Activate the indexing feature in the MidCOM configuration

Index your entire site

Create the Indexer Frontend

To make indexer run as a init.d script (on debian).

Drupal

Preface

Drupal side

MidCOM side

Edit your MidCOM styles to have the following links:

Midgard Documentation

Installing Midgard

Getting started

Site building

Application development

Midgard concepts

Midgard tools and configuration

Other information

How to set up site search using Solr

About Solr

Using solr-tomcat5.5

Using Jetty

Dependencies

A note on the `/var/lib/midgard/rcs` directory

`h` - Encode content as HTML

`H` - Encode content as HTML but keep entities verbatim

`f` - Format plain text to HTML

`F` - Format plain text to HTML with headlines

`p` - Execute content as PHP code

`u` - URL encode content

`s` - Show content as-is

`bind` and `port`

`logfile`

`loglevel`