From: grok Date: Thu, 11 Aug 2005 12:28:35 +0000 (+0000) Subject: adding new developers guide X-Git-Tag: LATEST_MERGED_1_1~124 X-Git-Url: http://erislabs.net/gitweb/?p=mir.git;a=commitdiff_plain;h=bb4eeae72f61c24d3795eb0ff433571005c16fab adding new developers guide --- diff --git a/ChangeLog b/ChangeLog index 8ace0aac..96b44c5c 100755 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,7 @@ -2005-08-10 Grok - * doc/diagrams: - adding a few diagrams to help document mir +2005-09-10 Grok + * doc/diagrams, doc/developpers-guide: + writing a developpers guide with diagrams to help + document mir 2005-08-07 Grok * templates/admin/FUNCTIONS.template: diff --git a/doc/developers-guide/developers-guide.xml b/doc/developers-guide/developers-guide.xml new file mode 100755 index 00000000..cabc2c76 --- /dev/null +++ b/doc/developers-guide/developers-guide.xml @@ -0,0 +1,51 @@ + + + + + ] +> + + Mir CMS 1.1, developpers guide + + + + 0.0.0 + + August 2005 + + First steps + + + + + + Grok + Mir coders + grok wants no spam _at_ no-log.org + + + + + Mir + indymedia + + + + + + + This document is meant for helping mir developpers. It is assumed that + you have allready installed mir and have some basic knowledge + on how to use it. However, reading the introduction chapter might + also be worthwhile for sysadmins and template designers. + + + + +&introduction; +&producers; + + \ No newline at end of file diff --git a/doc/developers-guide/introduction.xml b/doc/developers-guide/introduction.xml new file mode 100755 index 00000000..142b5648 --- /dev/null +++ b/doc/developers-guide/introduction.xml @@ -0,0 +1,176 @@ + +Introduction + +
Architecture overview + + Mir is a fairly large piece of software (over 50.000 lines) written in java. +It relies on the tomcat servlet framework for administration and open publishing +tasks. However, unlike many other CMS's that generate html on the fly +(usually using a cache), Mir writes html pages into a static site. +Normally, users that visit the mir site, will only see the static site. +Users that want to publish content (open publishing) will contact +the dynamic site. Administrators will also contact +the dynamic site (see figure). + + +
mir architecture (single host) + + + + + + + + +
+ + +This architecture is interesting because most page requests will be done +on the static site. Static pages are efficiently handled by the web server. +It is also interesting because it permits easy mirroring of the static +site. Mirrors are simple to set up, since only static pages are involved +(see figure). + + +
mir architecture (mirrored) + + + + + + + + +
+ +
+ +
Concepts used by Mir +Here's a list of important terms and concepts used by Mir. +Many of these concepts will be further detailed latter on in this guide. + + + producer + + As mentioned in the architecture overview, mir +generates a set of static html pages called the static site. +Generating these pages involves using a template engine to +replace variables (representing data) in template files. Template files +are written by web designers. +In many CMS systems, the available variables (data) are hard-coded into the +software. In practice, this is often not flexible enough +for web designers. +Mir allows designers to request the data they need by using +the producer framework, configured in the "producers.xml" file. + +Originally producers were +mostly used to generate pages, but they are now used for a lot of +other tasks. In fact, the producers.xml file provides a +simple, xml-based, programing (scripting) language, so that +site administrators can script their own custom tasks without +changing the java code. +For example, on indymedia.org, producers are used to pull rss +feeds for the global wire. + +
An example of article generation with the producers framework + + + + + + + + +
+ +Further information on producers may be found at XXX and in the javadoc +(classes Producer, NodedProducer, roducerNode...). + + + + + + database + + +Mir uses a postgres database to store it's data. +Currently, the mir.storage, mircoders.storage, mir.entity, and +mir.entity.adapter +packages +are used to acces the database in Mir. However, these packages +are obsolete and will be replaced by the +hibernate +object/relational persistence system. + + + + + + + localizer + + +FIXME localizers are to allow mir installations to add code seperate from the +main code. A lot of things can be changed in an installation (and are +by various mir sites). Think of custom open posting mechanism, open +posting validation, data model enhancements. + + + + + + generator + + +A generator is an abstraction for a template engine. +Different template engines are +supported right now: +freemarker +(used most often), tal (used by some +sites) and velocity (not used at all but supported anyway). + + + + + + + logger + + +Logging is understood here as "sytem logs" : information written +out to files that may be used to track what is going on in Mir, +especially errors and warnings. Mir uses the log4j logging system. +This alows us to split logs into different files, making them +easier to understand. + + + + + + mircoders packages + + +Originally, the mircoders packages were meant for local developpements, +as opposed to the core Mir code. This distinction is now obsolete +and these packages will probably be reorganized in future releases. + + + + + + bundles + + +bundles are key/value pairs in a text file, used for configuration +and internationalization + + + + + + +
+ + + + diff --git a/doc/developers-guide/producers.xml b/doc/developers-guide/producers.xml new file mode 100755 index 00000000..3a49c864 --- /dev/null +++ b/doc/developers-guide/producers.xml @@ -0,0 +1,9 @@ + +Producers framework + +
qsdqs + +sdfqsdf + +
+ diff --git a/doc/diagrams/article-generation-example.sxd b/doc/diagrams/article-generation-example.sxd index 8a1bc6f6..983926d8 100755 Binary files a/doc/diagrams/article-generation-example.sxd and b/doc/diagrams/article-generation-example.sxd differ diff --git a/doc/diagrams/mir-architecture-mirrored.sxd b/doc/diagrams/mir-architecture-mirrored.sxd index 2f8d20a0..ba9a170b 100755 Binary files a/doc/diagrams/mir-architecture-mirrored.sxd and b/doc/diagrams/mir-architecture-mirrored.sxd differ diff --git a/doc/diagrams/mir-architecture-singlehost.sxd b/doc/diagrams/mir-architecture-singlehost.sxd index 5bf0d72d..a0e01adf 100755 Binary files a/doc/diagrams/mir-architecture-singlehost.sxd and b/doc/diagrams/mir-architecture-singlehost.sxd differ