Table of Contents

• Using XoWiki
• Some XoWiki Showcases
  
• XoWiki as Development Toolkit

What is XoWiki?

• Wiki for OpenACS
• Full text search, categories, general-comments etc
• Stores everything in the content repository
• Revisions, reusable content, multi-language, user-tracking
• Easy to use, few markup commands, Xinha rich-text editor
• Customizable
• Easy integrated into existing applications
• Performance

Block Marker

Using Block-Markers

Glossary Link

• Used for definitions
• Browser reads pages using AJAX
• One XoWiki instance has to be named "glossary"
• Search sister-nodes then parent nodes until "glossary" is found
• Pages from other XoWiki instances refer to pages with the glossary link : [[glossary:pageName|?label?]]

Predefined Page Types

Page Types (3)

• xowiki::Page Template predecessor of ::xowiki::Form
  
• xowiki::PageInstance predecessor of ::xwowiki::FormPage
• older versions for backward compatibility
• Provide means to develop mini-apps (end-user programming)
  
• ::xowiki::Form and ::xowiki::FormPage introduced in next section

Example for ::xowiki::Object

# -*- tcl-*-

# Small example for demonstrating an ::xowiki::Object

# When the prototype page is loaded, the object named

# CGI will be added to the XoWiki package


::xowiki::Object new -title "CGI" -text {
  proc content {} {
    return "Hello \[\[Wiki\]\]-World. It is now [clock format [clock seconds]]."
  }
}

Rendered Content looks like:

XoWiki Prototype Pages

Stored in the file system (packages/xowiki/www/prototypes/)

Can be loaded into the CR of an xowiki instance (version control after the initial import)

Typical prototype pages:

• index page
• news
• book
• podcast
• sitemap.xml
  

Content Creators

• Calling interface with default values, values from url, provided values
  
• List all : {{available-includelets}}
• Examples:
• {{rss-button -span 10d -name_filter -title}}
• {{digg -description "" -url}}
• {{recent -max_entries 10}}
• {{get -variable title -source cover}}

Example Includelet: Timeline

• {{user-timeline -interval1 WEEK -interval2 YEAR}}

Relation between ::xowiki::Form and ::xowiki::FormPage

Two collaborating page types

• xowiki::Form:
  
• specifies additional variables,
  
• validators,
  
• renderers,
  
• mandatory parts, ...
• xowiki::FormPage:
  
• associated data,
  
• for one Form exist typically n FromPages 

Form Properties (2)

• Values are filled into HTML forms via tdom
• Forms can be built by a form-composer
  
• example: Compound Excercise Compound Excercise Answer
• Combination of HTML and auto-generated form fields possible (e.g. submit button added automatically)
• Form-fields can be rendered full (with label) or inline
  
• HTML-Form-part can contain auto-generated fields as well
  
• Example of inline rendering: Scales Scale-Entry
• Categories can be displayed on a per-form basis
  

Form Constraints

Form-constraints is a per-Form information specifying properties of form fields 

Form-constraints define

• Semantic properties and output formats for form-fields
• Types from content-repository attributes are inherited, wherever applicable (e.g. boolean type for field "anonymous instances")
  
• Form fields can define validators, which are checked on auto-generated fields and on HTML fields

Form Fields

Building blocks of ::xowiki::Forms

• Based on XOTcl classes (use inheritance, can be specialized, work with mixins...)
• All form-fields can be rendered inline or full (with label)
• Form-fields distinguish between internal and external representation (for e.g. sorting by month)
• Localization possible not only on connection locale, but also on entry-locale
  
• Uses DotLRN ZEN CSS 

Mini Applications based on Forms

FormPages can be used for developing small applications (mini-apps)

Two examples:

• Voting
• News 

Vote: FormPage

What did we not talk about...

• Tagging of pages
• Comments
• Notification
• Search
• Syndication (RSS, ...)
  
• etc ..

XoWiki based Applications

• Real-word and prototype showcases
  • Managing mailing lists
  • Keeping "learning diaries"
  • Providing web application "mash-ups"
• Developer tools
  • How to create your own page types
  • How to create your own includelets
  • How to create your own link types

Showcase / Hypermail2xowiki

Showcase / Hypermail2xowiki

Design decisions:

• Conversion of lists' mbox files into HTML documents by means of hypermail (see http://www.hypermail-project.org/)
• Replication at regular intervals into representations of XoWiki pages (::xowiki::PlainPage); attachments to postings are preserved as ::xowiki::File instances.

Showcase / iLogue

Showcase / iLogue

• iLogue is an attempt to ...
  • support the pedagogical intervention instrument of "personal learning contracts", originally proposed by ...
  • realize "personal learning contracts" that comprise ...
    • "Records of action": On-going reflection on learning progress
    • "Contract conversation": Elaboration and articulation of "goal sets"
    • "Review report": A reflection phase on the evolution of the contract and goal achievement
• Entirely built upon pre-existing XoWiki functionality which was simply refined by specializing toolkit features
• Added "in-place editing" on-top
• Get it from iLogue@sourceforge.net

Showcase/ Mupple

• Mupple: infrastructure for personal learning environments based on the mash-up metaphor
  • Presentation layer based on JS/Ajax toolkit adaptations
    • Grid-based screen with sortable columns
    • Windows presenting URLs (web application, includelets or feeds)
    • Windows can be reloaded, minimized, maximized or closed
    • New URLs can be added and launched
• XoWiki is used at the application/ data layer:
  • Prototypical use of XoWiki templates to share mash-ups of "web applets"
  • "Web applets" are realized using XoWiki's includelets
• Contact: felix.moedritscher@wu-wien.ac.at

XoWiki as Development Toolkit

• What are the most important ingredients for your XoWiki-empowered application?
  • Custom Content Types: XoWiki allows to define refined types of pages, so-called "page types"
  • Customized Link Types: You may also provide dedicated navigation units, so-called "typed links"
  • Custom Includelets: In case you want to enrich the authoring environment of users by "programmatic" elements that go beyond mere mark-up re-use
  • Custom Form-Fields: Provide Input/Output behavir
    

Operations on Pages

• Before focussing on advanced extension techniques (custom types etc.), some hints on basic interaction (CRUD) with XoWiki pages is appropriate:
  • (C)reate
  • (R)ead
  • (U)pdate
  • (D)elete
• This functionality is provided by xotcl-core through the Content Repository management layer, (see xotcl-core tutorial)

CRUD Example

# Prerequisites

# - Initialize package instance

::xowiki::Package initialize -url /xowiki

# - Get the id of the Content Repository Folder (folder_id)

set folder_id [$package_id folder_id]

# READ operation: Check, whether a page_name is already used

set page_name "my_page_[clock scan now]"

if {[::xo::db::CrClass lookup -name $page_name -folder_id $folder_id] == 0} {
  # We can CREATE the page

  # First create an XOTcl Object in memory

  ::xowiki::PlainPage create $page_name \
     -set text {This is the content of the new Page} \
     -set title {This is the Title of the new Page} \
     -name $page_name \
     -parent_id $folder_id \
     -package_id $package_id

  # persist the page in the content repository

  $page_name save_new

  # optionally, destroy the XOTcl object

  $page_name destroy
}

Creating/Updating Pages

Typical pattern

• Create an XOTcl page in memory
• Populate page object with actual values
• CREATE: persist page with method "save_new"
• UPDATE: create new revision with method "save"

Subclassing XoWiki's Page Types

By refining XoWiki's page type, one can reuse its functionality.

Steps involved:

• Step 1: Define a new Page Type as a subtype of one of the XoWiki Page types
• Step 2: Define a Form for editing your values
• Step 3:  Provide custom rendering behavior for the page type, i.e. by introducing a type-specific method render.

Includelets

Includelets are

• configurable content creators, available to page authors.
• Included in pages via {{rss-button}}

Defining a custom includelet:

• Step 1: Define a custom includelet class
• Step 2: Provide an appropriate rendering method for this class
  

Example: Embedding microformat geo-data in ordinary XoWiki pages:
    {{geo -longitude 90.516667 -latitude 14.616667}}

Typed Links

• Typed links allow content authors to establish different relationship types between XoWiki pages
• Define different kinds of relationships (see e.g. in W3C link types)
• How to provide new relationship types to XoWiki content authors?
  • Step 1: Define a new link class type
  • Step 2: Provide a type-specific renderer that needs to support
    • resolving the referenced page and
    • render the link text to be embedded into the rendering page

Custom Link Definition

# define link class

Class create ::xowiki::Link::cite -superclass ::xowiki::Link

::xowiki::Link::cite instproc render_found {href label} {
  # resolve the referenced page

  set item_id [my resolve]
  set reference [::xo::db::CrClass get_instance_from_db -item_id $item_id]

  # generate citation information

  set creation_date [::xo::db::tcl_date [reference set creation_date]]
  set creation_stamp [clock scan $creation_date]
  set user_id [$reference set creation_user]

  set author(url) [export_vars -base /shared/community-member {user_id}]
  set author(pretty_name)    [::xo::get_user_name $user_id]
  set published(pretty_date) $creation_date
  set published(raw)         [::xo::ical clock_to_iso $creation_stamp]

  return [subst {
   <cite class="hcite">
     <a class="fn url" href="$href">$label</a>
     <span class="author vcard">
       <a href="$author(url)" class="url fn">$author(pretty_name)</a>
     </span>
     <abbr class="dtpublished" title="$published(raw)">
     $publihsed(pretty_date)
     </abbr>
   </cite>
  }]
}

Custom Form Fields

• Custom form field allow content authors to provide form entries and custom renderers in ::xowiki::Forms
• Required Steps:
  • Step 1: Define a class for a custom form field
    
  • Step 2: Provide a renderer
  • Step 3: Use custom Form Field in an ::xowiki::Form
    

Basic Steps for Creating a Custom Form Field

1. Create a new Class 
   

   FormField::code_listing

   as subclass of ::xowiki::FormField::textarea. One can write the new class definition in an own package (see next section, subclassing xowiki), or by adding an additional file to xowiki/tcl/, but make sure this file is loaded after xowiki's form-field procs.
   
   By defining our new class as a subclass of ::xowiki::FormField::textarea we inherit the input semantics (when someone enters code example into a form page via editing the form page).

   In our new class, we define, the how pretty-printing of the code should be performed. For this purpose, we define a method pretty_value to compute the rendering, when a field of this type is viewed (see sample code on next page).

2. Create a new xowiki::Form instance from the user interface,
   
   
• define a form-field named e.g. "listing" "Form" or "Template" sections of the form, and
  
  
• specify that "listing" is of type "code_listing" (our newly defined class) in the form constraints with a form constraint like e.g. listing:code_listing.
  
  
3. The next page shows a form page with the new form field type in action.

Create an xowiki::Form in a script

#

# Sample snippet to show, how to create a form like 

# the one above programmatically

#


# Get package_id by initializing the package

::xo::Package initialize -url /xowiki

set template {
  @listing@
}
set fc {
  listing:code_listing
}

# Create a form instance in memory

set form_id [::xowiki::Form new -destroy_on_cleanup \
             -package_id $package_id \
             -parent_id [$package_id folder_id] \
             -name "en:sample.form" \
             -anon_instances "f" \
             -form {} \
             -text [list $template text/html] \
             -form_constraints $fc]

# save the form to the root folder of the package

$form_id save_new

Subclassing XoWiki

Define your own package (application) type

In order to define you won application type, the first step is define your own package type. Firstly, the new application myapp has to make sure, that the xowiki definitions are available. Secondly, the new package type can be defined.

For the application myapp, define in packages/myapp/tcl/myapp-procs.tcl the following

#

# make sure that xowiki is loaded

#

::xo::db::require package xowiki

# Define the package type


namespace eval ::myapp {

  ::xo::PackageMgr create ::myapp::Package \
      -package_key "myapp" -pretty_name "My Pretty App" \
      -superclass ::xowiki::Package
  ...
}

Request Resolver

The OpenACS request processor routes request for instances of some package type to the www directory of this type. One has therefore to provide a file packages/myapp/www/index.vuh, which is essentially a copy of the index.vuh file of xowiki.

::myapp::Package initialize -ad_doc {

  This is the resolver for this package. It turns a request into
  an object and executes the object with the computed method

} -parameter {
  {-m view}
  {-folder_id:integer 0}
}
::$package_id reply_to_user [::$package_id invoke -method $m]
ad_script_abort

References

• XoWiki Documentation
  • http://media.wu-wien.ac.at/download/xowiki-doc/
  • http://alice.wu-wien.ac.at:8000/xowiki-doc
  • http://alice.wu-wien.ac.at:8000/xowiki-faq
    
  • http://www.openacs.org/xowiki/XoWiki_User_Guide