Jun 19 2006

FEF - Forum Exchange Format

veröffentlicht von Mathias Bank

FEF - Forum Exchange FormatThis public specification describes interfaces for import and export between forum systems using XML.

Version 1.0

Published by Mathias Bank, http://mathias-bank.de

If your software supports FEF, you can use the icon for free, if you link to this page. A big thank to Lisa Petereit, who has created the logo and makes it available for free.

Thanks:

Special thanks go to those who helped me developing this specification. Listed in alphabetical order. I want to thank following people who helped to develop this specification:

Abstract:

This specification supports exchange of

  • categories (nested)
  • forum structure (nested)
  • Threads
  • Postings
  • private messages
  • User
  • UserGroups
  • right management for user and usergroups
  • attachements

Times:

Time stamps have to be stored according to the RFC822 format.

Markup:

Markup is supported in messages->message, postings->message, forum->descriptions, category>descriptions and user->signature.

Almost every forum uses a different markup language (BB-Codes, HTML,…). To be able to support an independent exchange format, this codes have to be translated into the Specification Markup Language (SML). This markup language supports every current known code. {If you miss something, please tell me}.

Each text consists of text nodes and xml nodes. An example is shown below.

Line breaks are realized with <br />. Paragraphs are not allowed (although it might be useful).

All suported xml tags including their optional attributes are listed below, where indention emphasizes its attribute character. All attributes are optional, but should be used if possible.

Each xml tag is a replacement of it’s corresponding code in a diffrent markup language.

Tag Attribute description
quote Used for quotes
src source address (absolute)
srcPostingID Reference to a posting, as long as quote is an internal quote (has to be the corresponding posting ID)
time RFC822 - time stamp of quote
userID userID, in case you need reference to an user
userName user name, indicating author of original text
underline underlines a text
strong bold text / strong emphasized text
emphasize italic text / emphasized text
linethrough canceled text
overline text overlined
sub text posed lower
sup text posed higher
link a link (all sorts of links: mail, url,…)
href destination, protocoll type has to be encoded in destination.
relation relation to current page (e.g. extern, no-follow)
threadID reference to another thread
postingID reference to another posting
wiki defines a Wiki Link (e.g. <link wiki=”CSP”>Contstraint Satisfaction Problem</link> will be expanded (by your software!) to <a href=”http://de.wikipedia.org/wiki/CSP”>Constraint Statisfaction Problem</a >)
attachment Reference to an attachement (<attachement href=”/attach/sample.txt”>Load your textFile</attachement>)
href destination to the attachment (relative to document root)
description description of the attachement
offtopic used for offtopic text
img used for images. Content of the xml-tag displays alt-attribute
src source of the image (relativ to document root or absolute)
title title of image
align alignment of image. possible Values: “left”, “right”
code tag for inserting code
lang code-language (in lowercase): php, html, javascript, latex, lisp, c, c++, c#, delphi, perl, …
list creates a normal list
ordered if given, it will create an ordered list (ordered=”ordered”)
listitem creates a list item (only allowed in list-tags)
block creates a block
align text-alignment of the block. possible value: “left”, “center”, “right”
indent defines the size of the left padding (allowed in px, em)
span enables to create special formating
color color (css format)
highlight specifies the text to be highlighted (color not necessary): highlight=”highlight”
fontname fontname
fontsize font-size (allowed in px or em)
bgcolor Background-color (css format)
table creates a table
width table width (px, em, %)
sorting defines, whether the table should be sorted automatically. Columns starts with 0 and are seperated by semikolon: d(escending), a(scending)
Example: <table sorting=”1d;2;3″>…</table>
tr table row (only in table-tags)
th table header (only in tr-tags)
color color of table header
align text alignment (”left”,”right”,”center”)
sortable defines, if the table is sortable for this header (sortable=”sortable”)
td table cell (only in table-tags)
color color
align text alginment
colspan defines, whether the cell should be combined whith cells in next columns (int)
rowspan defines, wheterh the cell should be combined whith cells in next rows (int)
edit tag for edited content
userID userID, in case you need reference to an user
userName user name, indicating author of original text
time RFC822 - time stamp of quote
acronym defines a text as an acronym
full defines extended text for the acronym (for examle <acronym full=”World Wide Web”>WWW</acronym>)
noparse noparse texts should be not parsed for any bb-codes ore something like this

Threads:

Threads link to specification of first posting. This way number of postings a title of thread can be read easily.

Additionally threads can be enriched with tags depending on whether the software your forum system was created with supports it.

User:

Specification includes definition of a password hash. Please choose from plain/md5/kmd5/sha1. Other forms are not supported by this specification. If your software uses another form, you have to leave this field empty.

Please not: If you will import data and there is no supported password, you should not use an empty one. Use for security reasons a random passwort. Your users can than generate another one, which is mailed to their eMail adress.

Important: If your new forum software does not support those hashes there is no possibility to convert them. Passwords would have to be reset. This specification allows you to have multiple passwords e.g. for encryption with multiple different encryption processes.

If you link files that are on the same server the links have to be relative to DocumentRoot. For instance, the link to my avatar is “/images/avatar/3423.jpg”. Absolute URLs are only allowed for external references but not recommended.

User Groups:

A user can be part of multiple groups, therefore userID has to be listed under Members accordingly. There should be at least two user groups. Guests and Members. Rights can be set using these two groups (e.g. forum with ID 3 is publically readable (Threads -> 106, Postings -> 102) )

Right Management:

This specification supports import and export of user and group rights. Those rights are listed in following table. They are applicable on sole threads, forums, and tags. Whether those rights are supported depends on your running system. You may look it up in your system’s specification.

Of course, it is possible to disable any right for specific users (for example if you granted some rights to a group). Only use “-” to disable the right: so “-301″ disallows to use colors in postings.

rightID description
001 Create forum
002 Edit forum
003 Delete forum
004 Ban user
005 Edit user
006 Delete user
007 Create group
008 Edit group
009 Delete group
010 Mail to user
– –
101 Create Posting
102 Read postings
103 Read postings if already answered (related to thread)
104 Create a new Thread
105 Read thread(s)
106 Create poll
107 Poll: Vote
108 Download attachment
109 Upload attachements
110 Create user (normaly avaiable for all users, so give it your guests-account)
111 edit own profile (applicable for own pages as well)
112 View profile(s)
113 View member list
114 Edit signature
115 Use signature (user may use signature)
116 Edit avatar
117 Use avatar (usage permission)
118 Download vCard(s)
119 Read private message
120 Write private message
121 Use search
122 Use WhoIsOnline
– –
201 Edit Posting (also moving to another thread)
202 Delete Posting
203 Delete Posting
204 Edit Thread (also moving to another forum)
205 Delete Thread
206 View author’s data (IP/network stats)
207 Edit other’s profile data
– –
301 Allow user using colors in postings
302 Allow user using font-name in postings
303 Allow user using images in postings
304 Allow user using colors in messages
305 Allow user using font-name in messages
306 Allow user using images in messages

Permissions and restrictions have to be configured using right management:

  • For instance, if thread with ID is supposed to be visible only to Mods but invisible to visitors (GroupID 1) and registered users, userGroup 1 and 2 should have permission -106 AND -102 for thread 33.
  • If forum with ID 2 is supposed to be private, it has to be set to -102 and -106 for userGroup 1 and 2.

Actual implementation of your system is a different thing (e.g. saving in your forum). This specification however is as abstract as possible to grant import and export of data.

Attachements

The specification supports to export file attachements. The files have to be saved in your filesystem. With the help of sml you can link to these files (<attachement href=”/attach/sample.txt”>Load your textFile</attachement>). If your new software handles attachements in another way, it can import the data in this way.

Root Node:


<FEF version="1.0">
  ...
</FEF>

Forum Structure:


<structure>
  <categories>
   <category>
      <id>CatID</id>
      <title>CategoryName</title>
      <description>
        this is a
        <strong>small</strong>
        category description
      </desscription>
      <!-- Nested Categories possible! //-->
      <category>
        <id>CatID</id>
        <title>CategoryName</title>
          <description>
            this is a
            <strong>small</strong>
            category description
          </desscription>
        <!-- Nested Categories possible! //-->
      </category>
   </category>
  </categories>
  <forums>
   <forum>
     <id>ForumID</id>
     <catID>Category-ID</catID>
     <name>ForumName</name>
     <description>
        this is a
        <strong>small</strong>
        forum description
     </desscription>
     <moderator>ModeratorID1</moderator> <!-- userRights have to be set //-->
     <moderator>ModeratorID2</moderator>
     <!-- Nested forums possible -> SubForums supported //-->
   </forum>
  </forums>
</structure>

User:


<users>
    <user>
       <id>UserID</id>
       <nickname>HansWurst</nichname>
       <email>hanswurst@blubb.de</email>
       <passwords>
         <password hash="md5">encryptedPassword</password>
         <password hash="sha1">SHA1-encryptedPassword</password>
       </passwords>
       <name>Name + Prename (opt)</name>
       <birhtday>Day of Birth(RFC822) (opt)</birthday>
       <lastLogin>LastLoginTime(RFC822) (opt)</lastLogin>
       <registerTime>RegisterTime(RFC822) (opt)</registerTime>
       <signatur> Signature (opt - sml) </signatur>
       <avatar>AvatarLink (opt) </avatar>
       <profil><![CDATA[ Profile-Text (opt)]]></profil>
       <karma>43</karma> <!-- opt //-->
       <plusPoints>30</plusPoints> <!-- opt //-->
       <minusPoints>4</minusPoints> <!-- opt //-->
       <additionalData>
          <fieldName>icq</fieldName>
          <value><![CDATA[ 24234234 ]]></value>
       </additionalData>
       <additionalData>
          <fieldName>skype</fieldName>
          <value><![CDATA[ hansi ]]></value>
       </additionalData>
    </user>
</users>

User Groups:


<userGroups>
   <userGroup>
      <id>GroupID</id>
      <name>Group name</name>
      <description><![CDATA[ Description (optional) ]]></description>
      <public>1</public> <!-- 2=public visibility, 1=visible for
                                             registered users, 0=invisible //-->
      <members>
        <member>userID</member>
        <member>userID2</member>
      </members>
      <memberAvatar>Link to member picture (optional) - relativ to
                                              DocumentRoot</memberAvatar>
      <parents> <!-- optional: provides inheritance of user rights (multiple
                                              inheritance possible) //-->
          <parentID>Group1</parentID>
          <parentID>Group1</parentID>
      </parents>
   </userGroup>
</userGroups>

Right Management:


<groupRights>
   <groupRight>
       <groupID>gr</groupID>
       <right>right ID</right>
       <rightObjects> <!-- objects effect by current right//-->
         <threads>
           <thread>ThreadID</thread>
           <thread>ThreadID2</thread>
         </threads>
         <forums>
           <forum>ForumID1</forum>
           <forum>ForumID2</forum>
         </forums>
         <tags>
           <tag>Tag1</tag>
           <tag>Tag2</tag>
         </tags>
       </rightObjects>
       <endTime>expiration date of right(RFC822) (optional)</endTime>
   </groupRight>
</groupRights>
<userRights>
   <userRight>
       <userID>User ID</userID>
       <right>right ID</right>
       <rightObjects> <!-- objects effect by current right//-->
         <threads>
           <thread>ThreadID</thread>
           <thread>ThreadID2</thread>
         </threads>
         <forums>
           <forum>ForumID1</forum>
           <forum>ForumID2</forum>
         </forums>
         <tags>
           <tag>Tag1</tag>
           <tag>Tag2</tag>
         </tags>
       </rightObjects>
       <endTime>expiration date of right(RFC822) (opt)</endTime>
   </userRight>
</userRights>

Threads:


<threads>
   <thread>
      <id>Thread ID</id>
      <startPosting>postingID</startPosting>
      <tags>
        <tag>Tag1</tag>
        <tag>Tag2</tag>
      </tags>
      <forumIDs> <!-- In general it is possible to store one thread in multiple forums as
                       long as your software supports it. In any other case you are only supposed
                       to enter one ID //-->
         <forumID>Forum ID</forumID>
      </forumIDs>
      <views>53</views> <!-- optional //-->
      <attributes>  <!-- optional //-->
        <importance>3</importance> <!-- Priority of thread, normally: Normal=1,
                       Announcement=2, Important=3 //-->
        <!-- Note: Whenever a thread is supposed to be invisible it'S rights have to be set
                       accordingly. Although they are not stored here. //-->
      </attributes>
   </thread>
</threads>

Postings:


<postings>
   <posting>
      <id>PostingID (int)</id>
      <title><![CDATA[ PostTitel ]]></title>
      <message>
               This is a posting quoting myself from
	       <link href="http://mathias-bank.de">Forenblogger.de</link>
               <br />
	       <quote src="http://www.mathias-bank.de">From and to forum admins</quote>
               Pretty excited about how it will work.
      </message>
      <searchMessage><![CDATA[ Cleaned text for search (optional) ]]></searchMessage>
      <parent>ParentID (int) (opt)</parent> <!-- If no parentID is given, then start of
                             a thread, trees are possible, in case
      of a linearisation refer to thread start //-->
      <userID>55</userID>
      <postingIP>IP-Address of author (long!)</postingIP>
      <postingNetwork>Provider ID (optional)</postingNetwork>
      <time>PostingTime (RFC822)</time>
      <visible>1</visible> <!-- 1 visible, 0 invisible (e.g. locked by moderator) //-->
      <edits>
       <edit>
        <editUser>userID</editUser>
        <editTime>time stamp of last edit (RFC822)</editTime>
        <editReason><![CDATA[ Reason for editing (opt) ]]></editReason>
       <edit>
      </edits>
   </posting>
</postings>

Privat messages:


<messages>
   <inbox>
      <message>
        <id>messageID (int)</id>
        <from>SenderID</from>
        <fromNick>SenderNick (opt)</fromNick>
        <sendTime>Time when message was sent (RFC822)</sendTime>
        <readTime>Time when message was read (RFC822) (optional)</readTime>
        <message>This is a message quoting myself from
	       <link href="http://mathias-bank.de">Forenblogger.de</link>
               <br />
	       <quote src="http://www.mathias-bank.de">From and to forum admins</quote>
               Pretty excited about how it will work.
        </message>
        <refID>5</refID> <!-- optional, provides references to other messages //-->
      </message>
   </inbox>
   <outbox>
      <message>
        <id>messageID (int)</id>
        <to>
          <id>recipientID1</id>
          <nickName>Hansi (opt)</nickname>
        </to>
        <to>
          <id>recipientID2</id>
          <nickName>Hansilein (opt)</nickname>
        </to>
        <sendTime>Time when message was sent (RFC822)</sendTime>
        <readTime>Time when message was read (RFC822) (opt)</readTime>
        <message>This is a message quoting myself from
	       <link href="http://mathias-bank.de">Forenblogger.de</link>
               <br />
	       <quote src="http://www.mathias-bank.de">From and to forum admins</quote>
               Pretty excited about how it will work.
        </message>
        <refID>10</refID> <!-- optional, provides references to other messages //-->
      </message>
   </outbox>
</messages>

Bisher 2 Reaktionen

  1. # Sascha A. Carlinon 5. August 2006 at 12:44

    Hi Matthias ;) Gibt es schon eine Referenzimplementierung von FEF?

  2. # Mathias Bankon 5. August 2006 at 17:04

    Nein, noch nicht. Ich kann derzeit leider auch nicht sagen, ab wann ich eine zur Verfügung stellen kann, da die Zeit derzeit knapp geworden ist. Falls sich also jemand an einer OpenSource-Implementierung machen will, hätte ich nichts dagegen :)

Trackback URI | Comments RSS

Die Klowand wartet auf dich! Beschreib sie!