WandoraWiki - User contributions [en]

Wandora

2015-05-29T12:52:34Z

Olli: /* Extractors */

This page collects Wandora's documentation. The documentation is a work in progress and incomplete. Also note some documentation may be out of date as the application is developed actively. If you need any specific help, write your question to the [http://wandora.org/forum/ discussion forum]. [https://www.youtube.com/channel/UClJoFDmiThA02RmAUT5YEcw Wandora's YouTube channel] has several tutorial videos reviewing some application features. Would you like to edit this wiki, send an email to {{wandora email address}} with your name and information about how you'd like to contribute. Please, remember to add keyword WANDORA to the title of your email. If you just popped in this wiki and don't know Wandora, please see also our landing page at http://wandora.org/ for a general information.

== Introduction ==

Wandora is a general purpose information management application. The application is written in [http://www.oracle.com/technetwork/java/index.html Java programming language] and it's internal data model is based on [[Topic Maps]]. Also, Wandora is a desktop application with a graphical user interface, layered data storage, huge collection of data extraction, import and export options and embedded HTTP server. Wandora's license is [http://www.gnu.org/licenses/gpl-3.0.txt GNU GPL version 3].

* [[General FAQ]]
* Wandora poster in [http://wandora.org/download/other/poster09.pdf PDF] or [http://wandora.org/download/other/poster09.gif GIF] formats.
* [[Features]]
* [[Screenshots]]
* [http://wandora.org/www/news Wandora news]
* [[License of Wandora|License]]

== Starting with Wandora ==

Wandora is a desktop application written in Java version 7. You need a Java Runtime Environment (JRE) to execute the application. Wandora has two distribution packages. A binary distribution package contains a runnable version of the application. Wandora's source code is available as a source code distribution package. Both packages are zip compressed file repositories. Use one of the startup scripts in '''bin''' folder to start the Wandora application.

* [[System requirements]]
* [[Change log]]
* [[Download|Download Wandora]] (build date {{build date}})
* [[How to install Wandora|Installing Wandora]]
* [[Running Wandora]]
* [[Tuning Wandora for Mac OS]]
* [[Quickstart]]

== Topic Maps ==

Wandora's internal datamodel is based on Topic Maps. [http://en.wikipedia.org/wiki/Topic_Maps Wikipedia defines Topic Maps] as a standard for the representation and interchange of knowledge, with an emphasis on the findability of information. A topic map represents information using ''topics'', ''associations'' and ''occurrences''. Topic represents any concept, from people, countries, and organizations to software modules, individual files, and events. Associations are hypergraph relationships between topics. Occurrence is an information resource relevant to a particular topic. If you are not familiar with Topic Maps, you can think it as a special kind of graph with nodes and edges. Wandora's topic map model is limited. These model limitations are explained in [[Reduced Topic Maps|Topic maps in Wandora]] page.

* [[Topic Maps|About topic maps]]
* [[Reduced Topic Maps|Topic maps in Wandora]]

See also '''Topic map layers''' section below. Wandora Team has converted several well known ontologies to Topic Maps format. These ontologies: WordNet, OpenCyc, Gene Ontology, Gellish, and Finnish General Upper Ontology (YSO) are available at [[Topic map gallery]].

== Using Wandora ==

This section contains basic tutorials for Wandora. If you are a novice Wandora user, please start here. See also tutorial videos on [http://wandora.org/wandora/tv/ wandoratv].

* [[Quickstart]]
* [[Opening a topic]]

Wandora has a rich set of topic, association and occurrence editing features. Usually a topic is edited in a topic panel one by one. Editing an association takes place in a separate association editor. Similarly, editing an occurrence takes place in an occurrence editor. Next pages discuss about creating and editing topics and associations.

* [[Create new topic]]
* [[Delete topic]]
* [[Create new association]]
* [[Delete association]]
* [[Editing topics and associations]]

Wandora saves all topic maps in a Wandora project file. Addition to project files, Wandora can read and write topic map serializations. See also chapter Import and Export below.

* [[How to save and load project]]
* [[How to import existing topic map to Wandora]]
* [[How to export topic map in Wandora]]

Next pages discuss some other features of the Wandora application.

* [[Finding a topic]]
* [[Topic shortcuts]]
* [[Working with topic tables]]
* [[Working with topic trees]]
* [[Drag and drop topics]]
* [[Creating custom topic trees]]
* [[View all variant names of a topic]]
* [[Transform variant names to topics and associations]]
* [[Undo and redo]]

== Topic panels ==

Topic panel is Wandora's user interface element to view and edit topics. Wandora supports several different topic panel types. Topic panels are managed with menu options under '''View'''. Wandora can view several topic panels simultaneously. Traditional topic panel views all topic elements in a table while tabbed panel views topic details in separate tabs. Graph topic panel is used for graph visualizations. Custom topic panel is based on user specific queries related to the current topic.

* [[Working with topic panels]]

Different topic panels are

* [[Traditional topic panel]]
* [[Tabbed topic panel]]
* [[Graph topic panel]]
* [[Custom topic panel]]
* [[Treemap topic panel]]
* [[R topic panel]]
* [[Processing topic panel]]
* [[Sketch grid]]
* [[Webview]]
* [[Tree panel]]
* [[Search panel]]
* [[Layer info panel]]
* [[Query editor topic panel]]

== Topic map layers ==

Wandora supports layered topic maps. Layered topic map contains one or more topic maps stacked into an ordered array. Any topic in the layered topic map is a superposition of all merging topics in different layers. Wandora views all layered topic maps as a single topic map but allows layer specific operations too. It really matters what layer is active. As user can focus on one layer at a time or replace any layer at any time, the composition of information is flexible. User can easily try different scenarios. Layer specific application options and tools locate in '''Layers''' menu. Layered topic maps are very close to the concept of [http://arxiv.org/abs/1309.7233 multilayer networks].

* [[Introduction to Layered Topic Maps]]
* [[Creating new layers]]
* [[Deleting layer]]
* [[Layer order and arranging layers]]
* [[Merging layers]]
* [[Topic's layer distribution]]

'''Different layer types'''
* [[Layered topic map]]
* [[Memory topic map]]
* [[Database topic map]]
* [[Linked topic map]]
* [[Query topic map]]

* [[Web service topic map]]

'''Other'''
* [[Compare topic maps]]
* [[Topic map patcher]]

== Import and Export ==

Wandora has been designed for easy aggregation of information and features a wide range of import and export tools. Wandora imports not just different Topic Maps formats such as XTM1, XTM2, and LTM but also RDF as XML, N3, and Turtle. Also, Wandora imports bio-ontologies in OBO flat file format. To get an up-to-date overview of Wandora's import options see menu '''File > Import'''. Addition to import options, Wandora features a wide range of export options from different Topic Maps formats to different graph formats. See menu options in '''File > Export'''. Wandora's native file format is Wandora project, with a file suffix WPR, which is a collection of XTM2 topic maps and a configuration file within a zip package.

* [[How to save and load project]]
* [[How to import existing topic map to Wandora]]
* [[How to export topic map in Wandora]]
* [[Waiana import and export]]
** [[Maiana import and export]]
* [[Transferring data with clipboard]]
* [[Importing RDF]] (see also extractors below)
* [[OBO flat file import|Importing OBO flat file ontologies]]
* [[Gene Ontology Annotation file import]]
* [[Importing XML with XSL]]
* [[Generic SQL database import]]
* [[Exporting WWW site]]
* [[Lucene search index export]]
* [[SQL Dump Export]]
* [[IoT Pinger]]

'''Graph and matrix imports'''
* [[Adjacency list import]]
* [[Adjacency matrix import]]
* [[Incidence matrix import]]

'''Graph and matrix exports'''
* [[Graph Modeling Language export]]
* [[GraphML export]]
* [[GraphXML export]]
* [[GXL graph export]]
* [[Export adjacency matrix]]
* [[Export incidence matrix]]
* See also page [[Graph topic panel]] and it's chapter Export options.

For additional information about Wandora's export capabilities see also '''Wandora as a server''' section below. For additional information about Wandora's import capabilities see also '''Extractors''' section below. 

== Extractors ==

[[Image:Wandoras_extractors.gif|center]]

Wandora is great for information mashups. With Wandora you can easily mashup information from various sources. Extractors are specific Wandora tools used to extract topics and associations out of different file formats and sources. For example, Wandora can extract data from MP3 and JPG files. To see what extractors your Wandora has installed see menu options in '''File > Extract'''. To start an extractor select the extractor in the menu or use drag and drop extractor. Wandora also features an add-on for Mozilla Firefox WWW browser. With this add-on you can perform extractions directly in Firefox www browser or in Thunderbird email client.

* [[Drag and drop extractor]]
* [[Wandora Firefox plugin|Firefox plugin]] to extract directly from Firefox WWW browser and Thunderbird email client.

{| cellspacing="0" cellpadding="0" width="100%" background-color="transparent"
| style="border:none; margin:none; padding:0px;" valign="top" | 

'''Search engine extractors'''
* [[Bing extractor]]
* [[Yahoo! BOSS extractor]]
* [[DuckDuckGo extractor]]
'''Simple files extractors'''
* [[JPG binary metadata extractor]]
* [[PDF extractor]]
* [[File system extractor]]
* [[Simple Text Document Extractor|Convert simple text documents to topic map occurrences]]
* [[Simple CSV association extractor]]
* [[OCR Extractor]]
'''Media extractors'''
* [[Europeana extractor]]
* [[MP3 ID3v1 and ID3v2 extractor]]
* [[IMDB extractor]]
* [[FreeDB extractor]]
* [[Last.fm extractors|Convert Last.fm XML feeds to a topic map]]
* [[Flickr extractors]]
* <strike>[[Ovi shared media extractors]]</strike>
* [[YouTube extractor]]s
* [[Rekognition extractor]]
'''Social and Bookmark extractors'''
* [[Facebook Graph extractor]]
* [[Twitter extractor]]
* [[Twitter JSON extractor]]
* [[Reddit extractor]]
* [[Digg extractors]]
* <strike>[[Delicious extractors]]</strike>
* <strike>[[Diigo bookmark extractor]]</strike>
* <strike>[[Twine RDF extractor]]</strike>
'''Bibliographical extractors'''
* [[MARCXML extractor]]
* [[Dublin Core XML extractor]]
* [[Bibtex extractor|Convert BibTeX files to a topic map]]
* [[RIS extractor]]
* [[HelMet library data extractor]]
'''Classifications'''
* [[GATE/ANNIE integration|GATE/ANNIE]]
* [[Stanford Named Entity Recognizer integration|Stanford Named Entity Recognizer (NER)]]
* [[OpenCalais classifier]]
* [[AlchemyAPI extractors]]
* [[Yahoo! YQL term extractor]]
* <strike>[[Tagthe extractor]]</strike>
* <strike>[[SemanticHacker classifier]]</strike>
* [[Zemanta extractor]]
* [[UClassify integration]]
* [[Simple Word Matching Extractor]]
* [[Similarity Word Extractor]]

'''Knowledge extractors'''
* [[OpenCyc extractor]]
* <strike>[[Subj3ct record extractor]]</strike>
* [[DBpedia extractor]]
* [[Freebase extractor]]
* [[Umbel extractors]]

| style="border: 1; margin:5; padding-left: 20px;" valign="top"| 

'''HTML structures extractors'''
* [[HTML superclass-subclass list extractor]]
* [[HTML instance list extractor]]
* [[HTML property table extractor]]
* [[HTML association table extractor]]
* [[HTML link extractor]]
'''News and syndication extractors'''
* [[RSS 2.0 Extractor]] and [[RSS 1.0 RDF Extractor]]
* [[Atom extractor]]
* [[New York Times Article Search API extractor]]
* [[New York Times Event API extractor]]
* [[Guardian open platform extractor]]
'''Microformat extractors'''
* [[Any23 extractor]]
* [[Geo microformat extractor|Convert geo microformat snippets to topic maps]]
* [[Adr microformat extractor|Convert adr microformat snippets to topic maps]]
* [[HCalendar microformat extractor|Convert hcalendar microformat snippets to topic maps]]
* [[HCard microformat extractor|Convert hcard microformat snippets to topic maps]]
'''Wiki extractors'''
* [[Wikipedia extractor]]
* [[MediaWiki Content Extractor]]
* More general [[MediaWiki extractor]]
'''Simple RDF extractors'''
* [[SKOS RDF extractor]]
* [[Dublin Core RDF extractor]]
* [[FOAF RDF extractor]]
* [[IIIF RDF extractor]]
'''Language'''
* [[Big Huge Thesaurus API extractor]]
* [[VerbOcean extractor]]
* [[Moby thesaurus extractor]]
* [[Stands4 word describer]]
'''Databases'''
* [[Generic SQL database import | Importing SQL database]]
* [[SQL query result set extractor]]
* [[Excel extractors]]
'''Other'''
* [[Email extractor]]
* [[Geonames extractors]]
* [[Gellish ontology extractor]]
* [[GEDCOM extractor]]
* [[SPARQL extractor]]
* [[Oma kaupunki extractor]]
* [[iCal calendar format extractor]]
|}

See [[Refining occurrences]] for some practical examples of how to extract associations and topics out of occurrences.

== Generators ==

Generators are special tools that generate topics and associations algorithmically. Generators help you construct basic building blocks for your topic maps. Generators are also a nice test suite for Wandora and topic maps in general. Generators locate in Wandora's '''File > Generate''' menu. Available generators are

* [[Random graph generator]]
* [[Fully connected graph generator]]
* [[Tree graph generator]]
* [[Linear list graph generator]]
* [[Finite group graph generator]]
* [[Platonic solid graph generator]]
* [[Hypercube graph generator]]
* [[Tiling graph generator]] (square, triangular, and hexagonal tilings)
* [[Edge generator]]
* [[L-system generator]]
* [[Cylinder graph generator]]
* [[Lattice graph generator]]

== Schema ==

Schema is a collection of specific topics and associations that Wandora uses to construct the user interface of association editor, occurrence editor and topic name panel. Schema eases many topic map operations such as association and occurrence construction. Schema also defines the language support of Wandora application.

* [[Schema]] to ease association and occurrence creation and modification

== Language support ==

Wandora supports only one base name per topic. However, a topic may contain several different variant names. Each variant name has a type and a language. Similarly, a topic may contain several different occurrences, text fragments. Each occurrence has a type and a language also. Wandora supports both Microsoft Translator and Google translate API and can convert both variant names and occurrences to other languages.

* [[How to add a language to Wandora]]
* [[How to add a name type to Wandora]]
* [[Translating variant names with Google]]
* [[Translating occurrences with Google]]
* [[Translating variant names with Microsoft Translator]]
* [[Translating occurrences with Microsoft Translator]]
* [[View all variant names of a topic]]

== Analyzing and querying topic maps ==

Generally these tools locate in '''Layers > Statistics''' menu. As an exception SOM classifier is found in association table menu and topic map comparison in '''File''' menu. Wandora provides also a bridge to R language. R language is a comprehensive statistical and graphing environment. With Wandora's R integration, the user can access Wandora's information structures in R environment. This opens up interesting possibilities if used together with information extractors.

* [[Topic map info]]
* [[Topic map connection statistics]]
* [[Topic map diameter]]
* [[Merge ratio matrix]]
* [[Export similarity matrix|Topic similarity matrix]]
* [[Clustering coefficient]] of topic map
* [[SOM classifier]] (Self Organizing Maps classifier)
* [[Asset weight of a topic]]
* [[Compare topic maps]]
* [[R in Wandora]]
** [[Statistical analysis of Topic Maps in R]]
* [[Query language]]
* [[TMQL]]

See the '''Extract''' section and especially the subsection '''Classifications''' above also.

== Tools and tool manager ==

A tool packs certain Wandora functionality into a single software component, specifically a Java class. When ever the user performs an action in Wandora, Wandora runs the tool that is responsible for the action. The Tool manager is a specific tool used to manage tools and tool sources. The user can install new tools to the Wandora. To develop a tool for the Wandora, the user writes a Java class source using a Java IDE, preferably Netbeans, and compiles the source using Java JDK.

* [[Tool manager]]
* [[:Category:Tools|Available tools]]
* [[Writing your own tool]]
* [[Installing your own tool]]
* [[Tool locks]]
* [[Configuring tools]]
* [[Additional tool help]]
* [[Developing Wandora]]

== Wandora as a server ==

The Wandora application contains an HTTP server. The embedded HTTP server generates various output formats and interactive visualizations out of the information stored in the Wandora. The embedded server hosts service modules. A service module is a software component that serves some information out of the Wandora. For example, '''HTML service module''' generates a navigable HTML site out of the topics in the Wandora. '''D3 graph service module''' generates an interactive graph out of all topics in the Wandora. More over, '''XTM topic map service module''' outputs current topic in the Wandora in an XTM format. It provides a data access point for external applications, or for other instances of the Wandora application. Some service modules rely on extracted information. Such service modules are '''Timeline service module''' and '''Google Maps service module'''.

* [[Embedded HTTP server]]
** [[HTML service module]]
** [[Mobile HTML service module]]
** [[RSS feed service module]]
** [[SOAP web service module]]
** [[Drupal service module]]
** [[Firefox and Thunderbird plugin service module]]
** [[XTM topic map service module]]
** [[JTM topic map service module]]
** [[RDF service module]]
** [[GRAPHML service module]]
** [[Screencast service module]]
** [[Flash graph service module]]
** [[Timeline service module]]
** [[Google Maps service module]]
** [[D3 graph service module]]
** [[D3 word cloud service module]]
** [[D3 partition service module]]
** [[D3 tree service module]]
** [[D3 matrix service module]]
** [[D3 layer visualization]]
** [[Waiana service module]]
** [[SameAs service module]]

Wandora team has also built several service modules for Drupal content management system and an extra for Joomla content management system. These modules can be used to publish Wandora stored information in these CMSes.

* [[Wandora Drupal extras]]
* [[Wandora's Joomla Topic Reader]]
* [[JQuery Mobile based topic map browser]]

Wandora's embedded HTTP server contains a service module for SOAP web service. There is additional information available for Wandora's web service.

* [[Wandora Web Service]]

Also included is a [[Wandora modules framework|modular framework]] for building webapps in Apache Tomcat or similar servlet containers. Topic maps and features of Wandora can be included in the servlet using this framework. The same framework can also be used in the embedded server.

== Developing and hacking Wandora ==

Wandora project is developed with [http://netbeans.org/ Netbeans IDE]. Wandora's source code distribution package contains a Netbeans IDE project. You can download Wandora's source code distribution package from [[Download]] page. However, we suggest that you clone [https://github.com/wandora-team/wandora Wandora's repository] at Github. Perhaps you want to push some fixes or new features back.

* [[Change log]]
* [https://github.com/wandora-team/wandora Wandora @ Github]
* [[Download]] (build date {{build date}})
* [[License of Wandora|License]]
* [[Developing Wandora]]
* [http://wandora.org/api/ Wandora Javadocs], [http://wandora.org/api/wandora-javadoc.zip download]
* [[Wandora's configuration file]]
* [[Upcoming features]]
* [[Open bugs]]

See also section '''Tools and tool manager''' above.

== Papers and presentations ==

This section lists some papers and presentations related to Wandora and semantic web technologies created by the inner circle of Wandora Team. For a more wider selection of works related to Wandora see [http://wandora.org/forum/viewforum.php?f=10&sid=57134deccd5ba47132334f2f1215b520 Use cases at Wandora forum].

* [http://tmra.de/2010/ TMRA 2010] tutorial slides: [http://wandora.org/download/other/tmra10/wandora_workshop_tmra2010.pdf Converting information to Topic Maps using Wandora].
* [http://tmra.de/2009/ TMRA 2009] workshop presentation [http://www.slideshare.net/tmra/semantic-mashups-with-wandora Semantic Mashups with Wandora]. [http://wandora.org/wandora/download/other/tmra09/wandora_tutorial_leipzig.zip Example data set] is available for brave experimenters.
* Wandora poster in [http://wandora.org/wandora/download/other/poster09.pdf PDF] or [http://wandora.org/wandora/download/other/poster09.gif GIF] formats.
* Kivelä A.: [http://wandora.org/download/other/gradu_kivela.pdf OBO-ontologioiden kuvaaminen Topic Map-muotoon]. MSc Theses, 2008. (in Finnish). (English Abstract: [http://wandora.org/wandora/download/other/gradu_kivela_abstract_en.pdf Converting OBO ontologies to Topic Maps]).
* Lyytinen O.: [http://www.wandora.org/download/other/gradu_lyytinen.pdf Semanttisen webin tekniikoiden soveltaminen Wikisovelluksissa]. MSc Theses, 2008. (in Finnish)
* Kivelä A.: [http://www.wandora.org/download/other/wandora_xml_finland.pdf Topic Maps, Wandora ja kourallinen julkaisuprojekteja] (in Finnish). Presentation held in XML Finland meeting November 14th, 2007.
* Lyytinen O.: [http://wandora.net/wandora/download/other/step06.pdf Building Internet Services with Layered Topic Maps]. Presentation held in The Finnish Artificial Intelligence Conference (STeP 2006), 2006-10-26.
* Kivelä A., Lyytinen O.: [http://wandora.net/wiki/images/Topic_map_aided_publishing.pdf Topic Map Aided Publishing – A Case Study of Assembly Media Archive]. ''Web Intelligence. STeP 2004 - The 11th Finnish Artificial Intelligence Conference Proceedings - Vol. 2'', 2004.

== Wandora @ World ==

* [https://github.com/wandora-team/wandora Github]
* [http://twitter.com/#!/wandora_app Twitter]
* [https://www.youtube.com/channel/UClJoFDmiThA02RmAUT5YEcw YouTube]
* [http://freecode.com/projects/wandora/ Freecode]
* [http://sourceforge.net/projects/wandora/ SourceForge.net]

* [http://www.topicmapslab.de/projects/wandora?locale=en Topic Maps Lab]

== See also ==

As said in the very beginning, the documentation is a work in progress and incomplete. If the available documentation didn't answer your question, please drop a line to Wandora forum and we'll try to find an answer for you.

* [[General FAQ]]
* [[FAQ for Wandora user]] reveals some nifty details of Wandora application.
* [http://wandora.org/tv Wandora tv]
* [http://wandora.org/forum/ Wandora forum]
* [[Open bugs]]

If you are interested in Topic Maps and information technology related news see [http://planet.topicmaps.org/ Planet Topic Maps] and [http://planetrdf.com/ Planet RDF].

IIIF Export

2015-05-29T12:23:47Z

Olli: Protected "IIIF Export" (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite))

IIIF Export tool exports image data in the [http://iiif.io/ International Image Interoperability Framework] JSON-LD format. To use the IIIF Export, select the menu item '''File > Export > Export IIIF JSON-LD...'''.

IIIF manifest files can be used with some 3rd party image viewers, such as the [https://github.com/IIIF/mirador Mirador Viewer]. However, at the moment Mirador does not support static image links in the manifest but instead requires an IIIF image server to host the images. As such, the simple IIIF manifest files exported from Wandora may not be usable in Mirador. The Full IIIF Builder (described below) will export the image server information, if it was specified in the topic map, and as long as the images are correctly hosted on the server, these files should then work in Mirador.

There are several options in how the image data is gathered from the topic map. You can change this by launching the tool with holding down the control key and then changing the IIIF Builder option. The different builders are described below.

'''Simple Selection Builder''' takes the selected topics and looks for images in their subject locator. An IIIF image manifest is then generated from these images. Topic display names are used as labels of the images but no other information is used from the topic map. As such, this is a very simple way to export the selected image topics as IIIF JSON-LD.

'''Selection Instances Builder''' is similar to the simple selection builder, but instead it checks the instances of the selected topics for image subject locators rather than the selected topics themselves. For example, you might have a topic called ''images'' which is the type of all your image topics. You'd then select just the type topic and all its instances would be exported.

'''Full IIIF Builder''' uses the same topic maps schema as is produced by the [[IIIF RDF extractor]] tool. You need to select the manifest topic and then the tool will look for the associated sequences, canvases etc. This is the most full featured IIIF export tool.

See also [[IIIF RDF extractor]].

IIIF Export

2015-05-29T12:23:41Z

Olli:

IIIF Export

2015-05-29T12:18:36Z

Olli: Created page with "IIIF Export tool exports image data in the [http://iiif.io/ International Image Interoperability Framework] JSON-LD format. To use the IIIF Export, select the menu item '''Fil..."

IIIF Export tool exports image data in the [http://iiif.io/ International Image Interoperability Framework] JSON-LD format. To use the IIIF Export, select the menu item '''File > Export > Export IIIF JSON-LD...'''.

There are several options in how the image data is gathered from the topic map. You can change this by launching the tool with holding down the control key and then changing the IIIF Builder option. The different builders are described below.

'''Simple Selection Builder''' takes the selected topics and looks for images in their subject locator. An IIIF image manifest is then generated from these images. Topic display names are used as labels of the images but no other information is used from the topic map. As such, this is a very simple way to export the selected image topics as IIIF JSON-LD.

'''Selection Instances Builder''' is similar to the simple selection builder, but instead it checks the instances of the selected topics for image subject locators rather than the selected topics themselves. For example, you might have a topic called ''images'' which is the type of all your image topics. You'd then select just the type topic and all its instances would be exported.

'''Full IIIF Builder''' uses the same topic maps schema as is produced by the [[IIIF RDF extractor]] tool. You need to select the manifest topic and then the tool will look for the associated sequences, canvases etc. This is the most full featured IIIF export tool.

See also [[IIIF RDF extractor]].

IIIF RDF extractor

2015-05-29T12:10:53Z

Olli:

The IIIF RDF Extractor reads JSON-LD files conforming to the [http://iiif.io/ International Image Interoperability Framework]. To use the IIIF RDF Extractor, select the menu item '''File > Extract > Simple RDF formats > IIIF JSON-LD extractor...'''

The JSON-LD format is in the end an RDF serialisation format and as such, the extractor is a slightly modified RDF importer. Most commonly used RDF predicates are cleanly converted to equivalent topic maps structures. However, the imported data may contain any RDF triplets whatsoever and some might be lacking special handling instructions. These will be imported as generic RDF triplets the same way [[Importing RDF | RDF import]] does.

You can also import IIIF JSON-LD with the generic RDF import tool, you will then get all the triplets in the raw format without any processing.

See also [[IIIF Export]].

IIIF RDF extractor

2015-05-29T12:09:45Z

Olli:

IIIF RDF extractor

2015-05-29T12:08:29Z

Olli:

The IIIF RDF Extractor reads JSON-LD files conforming to the [http://iiif.io/ International Image Interoperability Framework]. The JSON-LD format is in the end an RDF serialisation format and as such, the extractor is a slightly modified RDF importer. Most commonly used RDF predicates are cleanly converted to equivalent topic maps structures. However, the imported data may contain any RDF triplets whatsoever and some might be lacking special handling instructions. These will be imported as generic RDF triplets the same way [[Importing RDF | RDF import]] does.

You can also import IIIF JSON-LD with the generic RDF import tool, you will then get all the triplets in the raw format without any processing.

See also [[IIIF RDF Export]].

IIIF RDF extractor

2015-05-29T12:07:18Z

Olli: Protected "IIIF RDF extractor" (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite))

2015-04-22T14:13:31Z

Olli: /* Query flow */

'''This is an upcoming feature and is not included yet in the public release.'''

Query editor topic panel is one of several different [[topic panels]] in Wandora. Its main purpose is to provide a graphical editor for the Wandora [[query language]], and a way to execute the queries in a topic panel. If you have a query ready, you can just open it in the editor and then execute it by double clicking a topic elsewhere in Wandora. This will open the topic in the current topic panel, which in this case means executing the query using the selected topic as the context. This way you can have a topic panel which gathers information about a selected topic through a customisable query.

[[File:Queryeditor.png|center]]

== Opening the topic panel ==

You can open the query editor topic panel by selecting '''New panel > Query editor''' from the '''View''' menu. This will open the panel and its subpanels that you use to open or build a query.

== Building queries ==

=== Basics ===

Queries are built graphically in the ''Graph Editor'' subpanel, which usually occupies most of the space. Please see the separate page [[query language]] for details about the general principles behind queries. As explained there, queries consist of directives, each of which perform a specific task. In the graphical editor, directives are represented by grey boxes, with the directive name as the title of the box.

Directives can be moved around the editor so that the structure of the query is easier to grasp. The position of directives in the graph does not affect the behaviour of the directive itself at all.

By clicking the title of a directive you can select it which opens it in the ''Inspector'' sub panel, usually at the lower right corner. The parameters and some other details of the directive can be modified here. Note that some of the parameters are reflected in a compact form in the directive box in the editor graph. This is for information only so that it's a bit easier to see what a specific directive does without opening it in the inspector. The parameters cannot be modified in the graph, only in the inspector.

In addition to all the other directives comprising your query, a box titled '''Final result'' will be present in the graph editor. This isn't strictly speaking a directive but it looks and acts like one. It's a sink where the final result of the query will be taken from. Thus, you'll want to direct the results of your query in there.

=== Adding directives from the directives list ===

You can add directives into the graph editor by dragging them from the ''Directives list'' subpanel, usually located in the top right corner. The same corner contains the ''Query library'' subpanel in a separate tab, you may need to select the list tab to access it.

All the directives are organised in the list by their category. You can add a directive onto the graph editor by dragging it from the list onto the graph. After this, you can move the directive around in the graph, modify it with the inspector and so on.

=== Connecting directives ===

In the query language model, directives take as an input a single result row, and usually only use the active value of the row. However the directives are usually organised by using the [[From (query directive) |From directive]] which essentially makes one directive take any number of rows as input.

Just like the textual script form has a special syntax for using from directives due to their special nature, so does the graphical editor. In the graphical editor from directives are usually represented as arrows going from one directive to another. The directive boxes themselves have two arrows in the top right and left corners. The arrow in the top left corner represents the output of a directive while the arrow in the top right corner represents the input. You can drag from the output arrow to the input arrow of a different directive to connect the two directives. Behind the scenes, a from directive is created to connect the two directives, but in the graph you will only see an arrow.

It is possible to add from directives as actual directive boxes into the graph by dragging them from the directives list. This however is hardly ever needed and makes the directive graph cluttered.

The from directive arrows always go from the left side of one directive box to the right side of another. In the graph you may also have arrows which connect to the bottom of a directive box. These do not represent from directives, they are directives used as parameters for other directives. These are explained in the next section.

Only a single directive can go as input to any one directive. However, you can join directives together by using the [[Join (query directive) |Join directive]]. Just drag it from the directive list onto the graph like any other directive. Then the directives that are to be joined are added in as parameters for the join directive, this is covered in the next section.

=== Editing directives with the inspector ===

When you click the title of a directive box in the query editor, that directive is opened in the directive ''Inspector'' panel, usually located in the bottom right corner.

The inspector works based on the underlying Java classes. Thus the documentation of all the directives in the [[query language]] page will be handy. In the inspector, you need to first select the constructor to use. Some directives only have a single choice but many have a few options. The different choices usually create slight variations of the directive.

After selecting the constructor, you will get fields for all the constructor parameters. Depending on the parameter type, the fields may look slightly different. Textual values get simple text fields; directive values get a drop element where another directive can be dragged and dropped; operands can be specified in different forms, so you'll need to first select how you intend to specify the operand value; finally arrays and collections will have buttons to add and remove new elements and then fields to specify each element.

As mentioned in the previous section, some directives are connected to other directives by being their parameters rather than through the form directive. The parameter directives connect to the bottom edge of another directive in the graph. To make the connection, first select the directive whose parameter you want to set. Then drag the outgoing arrow of another directive into the parameter drop target in the inspector.

The bottom of the inspector panel also has an ''Addons'' section. Directives have additional methods in them which may further modify the directive behaviour. Some of these addon methods are common to all directives, being inherited from the base Directive class. Some are unique to certain directives. To use addons, select the addon you wish to use from the list and click ''Add addon''. After this, you get a section with the parameters for the addon. You can fill in the parameters as you do for the constructor, including possibly using other directives as parameter values.

=== Query flow ===

When executing a query, some kind of an input row is used as the starting point. Ordinarily this will just contain the single selected topic. The execution of the query starts from the Final result box, which can be treated as directive even though it isn't really one. It gets the input row and then checks if another directive is connected to it using the from directive. If there is one, then the input row and execution is passed onto it. Whatever directive is connected, it will do its own thing and eventually return a set of result rows. The pseudo-directive Final result takes these result rows one at a time and then performs its own processing on each one separately. In this case, the processing can be said to be gathering the rows and then displaying them in a table.

The execution works similarly for any other directive. For example, take the [[Instances (query language) |Instances directive]]. It takes an input row, then checks if any other directive is connected and if so the input and execution is passed onto them. When they return with a set of result rows, the instances directive starts doing its job. It takes the result rows of the connected directive, one at a time, and then gets all the instances of the active column in the result row. The results of each individual input row are then combined and given as the final result of the instances directive and given to whichever directive preceded it.

Thus the execution goes from the Final result pseudo directive at the top all the way down the graph to the directives at the end of the chain. The initial input row gets passed down untouched until it reaches the directives at the end of the chain. Those then do their job with the initial input and their output works as the actual input to the higher up directives as the execution returns up the chain. And the Final result then takes the final output at the top of the chain.

If a directive contains other directives as parameters, they get processed when the execution returns to the directive after reaching the end of the chain first. The exact nature of how they are processed may depend on the directive taking them as parameters but the [[Count (query language |Count directive]], for example, gives a good idea of what generally happens. When execution returns to the count directive, after having gone through the whole chain, it starts doing its own processing. This processing is executing the parameter directive, using the input that Count got as the returning input from its connected directive. The results of the parameter directive are then counted and the count number is the output from the count directive. If there are multiple input rows, the parameter directive gets executed multiple times, once for each input. The parameter directive thus represents instructions on what exactly is to be counted, while the input to count acts as the context of where those instructions are applied. The instructions are the same for each input row, but the context is different so each input may get a different result.

This also demonstrates the typical difference between a parameter directive and a from directive, or the two different types of arrows in the graph. A parameter directive defines the behaviour of its containing directive somehow while the from directive just redirects input rows. As another example, the [[Join (query language) |Join directive]] joins the results of two (or more) directives using a cartesian product. The directives that are to be joined are given as parameters to the join directive. A from directive can also be used to specify what acts as input to the join, and subsequently to all its parameter directives.

=== Saving and loading directives ===

== Executing queries ==

Query editor topic panel

2015-04-22T14:01:50Z

Olli: /* Building queries */

'''This is an upcoming feature and is not included yet in the public release.'''

Query editor topic panel is one of several different [[topic panels]] in Wandora. Its main purpose is to provide a graphical editor for the Wandora [[query language]], and a way to execute the queries in a topic panel. If you have a query ready, you can just open it in the editor and then execute it by double clicking a topic elsewhere in Wandora. This will open the topic in the current topic panel, which in this case means executing the query using the selected topic as the context. This way you can have a topic panel which gathers information about a selected topic through a customisable query.

[[File:Queryeditor.png|center]]

== Opening the topic panel ==

You can open the query editor topic panel by selecting '''New panel > Query editor''' from the '''View''' menu. This will open the panel and its subpanels that you use to open or build a query.

== Building queries ==

=== Basics ===

Queries are built graphically in the ''Graph Editor'' subpanel, which usually occupies most of the space. Please see the separate page [[query language]] for details about the general principles behind queries. As explained there, queries consist of directives, each of which perform a specific task. In the graphical editor, directives are represented by grey boxes, with the directive name as the title of the box.

Directives can be moved around the editor so that the structure of the query is easier to grasp. The position of directives in the graph does not affect the behaviour of the directive itself at all.

By clicking the title of a directive you can select it which opens it in the ''Inspector'' sub panel, usually at the lower right corner. The parameters and some other details of the directive can be modified here. Note that some of the parameters are reflected in a compact form in the directive box in the editor graph. This is for information only so that it's a bit easier to see what a specific directive does without opening it in the inspector. The parameters cannot be modified in the graph, only in the inspector.

In addition to all the other directives comprising your query, a box titled '''Final result'' will be present in the graph editor. This isn't strictly speaking a directive but it looks and acts like one. It's a sink where the final result of the query will be taken from. Thus, you'll want to direct the results of your query in there.

=== Adding directives from the directives list ===

You can add directives into the graph editor by dragging them from the ''Directives list'' subpanel, usually located in the top right corner. The same corner contains the ''Query library'' subpanel in a separate tab, you may need to select the list tab to access it.

All the directives are organised in the list by their category. You can add a directive onto the graph editor by dragging it from the list onto the graph. After this, you can move the directive around in the graph, modify it with the inspector and so on.

=== Connecting directives ===

In the query language model, directives take as an input a single result row, and usually only use the active value of the row. However the directives are usually organised by using the [[From (query directive) |From directive]] which essentially makes one directive take any number of rows as input.

Just like the textual script form has a special syntax for using from directives due to their special nature, so does the graphical editor. In the graphical editor from directives are usually represented as arrows going from one directive to another. The directive boxes themselves have two arrows in the top right and left corners. The arrow in the top left corner represents the output of a directive while the arrow in the top right corner represents the input. You can drag from the output arrow to the input arrow of a different directive to connect the two directives. Behind the scenes, a from directive is created to connect the two directives, but in the graph you will only see an arrow.

It is possible to add from directives as actual directive boxes into the graph by dragging them from the directives list. This however is hardly ever needed and makes the directive graph cluttered.

The from directive arrows always go from the left side of one directive box to the right side of another. In the graph you may also have arrows which connect to the bottom of a directive box. These do not represent from directives, they are directives used as parameters for other directives. These are explained in the next section.

Only a single directive can go as input to any one directive. However, you can join directives together by using the [[Join (query directive) |Join directive]]. Just drag it from the directive list onto the graph like any other directive. Then the directives that are to be joined are added in as parameters for the join directive, this is covered in the next section.

=== Editing directives with the inspector ===

When you click the title of a directive box in the query editor, that directive is opened in the directive ''Inspector'' panel, usually located in the bottom right corner.

The inspector works based on the underlying Java classes. Thus the documentation of all the directives in the [[query language]] page will be handy. In the inspector, you need to first select the constructor to use. Some directives only have a single choice but many have a few options. The different choices usually create slight variations of the directive.

After selecting the constructor, you will get fields for all the constructor parameters. Depending on the parameter type, the fields may look slightly different. Textual values get simple text fields; directive values get a drop element where another directive can be dragged and dropped; operands can be specified in different forms, so you'll need to first select how you intend to specify the operand value; finally arrays and collections will have buttons to add and remove new elements and then fields to specify each element.

As mentioned in the previous section, some directives are connected to other directives by being their parameters rather than through the form directive. The parameter directives connect to the bottom edge of another directive in the graph. To make the connection, first select the directive whose parameter you want to set. Then drag the outgoing arrow of another directive into the parameter drop target in the inspector.

The bottom of the inspector panel also has an ''Addons'' section. Directives have additional methods in them which may further modify the directive behaviour. Some of these addon methods are common to all directives, being inherited from the base Directive class. Some are unique to certain directives. To use addons, select the addon you wish to use from the list and click ''Add addon''. After this, you get a section with the parameters for the addon. You can fill in the parameters as you do for the constructor, including possibly using other directives as parameter values.

=== Query flow ===

When executing a query, some kind of an input row is used as the starting point. Ordinarily this will just contain the single selected topic. The execution of the query starts from the Final result box, which can be treated as directive even though it isn't really one. It gets the input row and then checks if another directive is connected to it using the from directive. If there is one, then the input row and execution is passed onto it. Whatever directive is connected, it will do its own thing and eventually return a set of result rows. The pseudo-directive Final result takes these result rows one at a time and then performs its own processing on each one separately. In this case, the processing can be said to be gathering the rows and then displaying them in a table.

The execution works similarly for any other directive. For example, take the [[Instances (query language) |Instances directive]]. It takes an input row, then checks if any other directive is connected and if so the input and execution is passed onto them. When they return with a set of result rows, the instances directive starts doing its job. It takes the result rows of the connected directive, one at a time, and then gets all the instances of the active column in the result row. The results of each individual input row are then combined and given as the final result of the instances directive and given to whichever directive preceded it.

Thus the execution goes from the Final result pseudo directive at the top all the way down the graph to the directives at the end of the chain. The initial input row gets passed down untouched until it reaches the directives at the end of the chain. Those then do their job with the initial input and their output works as the actual input to the higher up directives as the execution returns up the chain. And the Final result then takes the final output at the top of the chain.

If a directive contains other directives as parameters, they get processed when the execution returns to the directive after reaching the end of the chain first. The exact nature of how they are processed may depend on the directive taking them as parameters but the [[Count (query language |Count directive]], for example, gives a good idea of what generally happens. When execution returns to the count directive, after having gone through the whole chain, it starts doing its own processing. This processing is executing the parameter directive, using the input that Count got as actual input from its connected directive. The results of the parameter directive are then counted and the count number is the output from the count directive. If there are multiple input rows, the parameter directive gets executed multiple times, once for each input. The parameter directive thus represents instructions on what exactly is to be counted, while the input to count acts as the context of where those instructions are applied.

The difference between a parameter directive and a from directive is that a parameter directive changes the behaviour of another directive somehow while the from directive just redirects input rows. For example, a players directive gets players of an association. It takes the type and roles of the association as parameters. These change the behaviour of the players directive by changing which associations and roles are used. The same association type and roles are used for all inputs. The from directive, on the other hand, just redirects different input rows for the players directive.

=== Saving and loading directives ===

== Executing queries ==

Query editor topic panel

2015-04-22T13:36:56Z

Olli: /* Building queries */

Query editor topic panel

2015-04-22T12:29:14Z

Olli:

2014-09-23T08:16:24Z

Olli: Protected "Concat (query directive)" (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite))

== Description ==

Executes the wrapped directive and concatenates the String representation of active column values from the results of that query. A delimiter string can be given optionally used between the concatenated values, the default value for this is "; ".

== Constructor ==

Concat(Directive directive[,String delimiter])

== Examples ==

Following example concatenates the base names of all the instances of the active topic.

importPackage(org.wandora.query2);
new Concat(
new BaseName().from(new Instances())
)

[[Category:Query directive]]

2014-05-16T09:51:27Z

Olli: Protected "D3 graph service module" (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite))

The D3 graph service module provides a graph visualization of the topic map in Wandora. The module is part of Wandora's embedded HTTP server. It is based on open source Javascript visualization library [http://d3js.org/ D3.js]. The service module's alias is '''d3graph''' and access URL

http://127.0.0.1:8898/d3/graph

The graph visualization provided by the D3 graph service module contains only binary associations and the number of viewed topics is limited to 1000 by default. This limitation can be overridden with the HTTP parameter '''n'''. For example, accessing URL

http://127.0.0.1:8898/d3/graph?n=9999

sets the maximum number of viewed topics to 9999. It depends on the client's computing resources whether or not the created visualization is usable with 9999 nodes. It requires a lot of computing power to view graphs with 1000 nodes or more. Screen capture below shows a d3graph visualization generated from Wandora's default topic map. User can zoom in and out the graph visualization using the mouse wheel. Dragging a node moves it while dragging the background pans the whole graph. Mousing over on a node fades out the other graph nodes.

[[Image:D3graph example 03.gif|center]]

The next screen capture shows a d3graph visualization of an output of [[Tiling graph generator|hexagonal tiling generator]] with a depth of 5.

[[Image:D3graph example 04.gif|center]]

== See also ==

* [[Embedded HTTP server]]
** [[HTML service module]]
** [[Mobile HTML service module]]
** [[RSS feed service module]]
** [[SOAP web service module]]
** [[Drupal service module]]
** [[Firefox and Thunderbird plugin service module]]
** [[XTM topic map service module]]
** [[JTM topic map service module]]
** [[RDF service module]]
** [[GRAPHML service module]]
** [[Screencast service module]]
** [[Timeline service module]]
** [[Google Maps service module]]

D3 word cloud service module

2014-05-16T09:51:18Z

Olli: Protected "D3 word cloud service module" (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite))

The D3 word cloud module uses the [http://www.jasondavies.com/wordcloud D3 cloud layout] to visualize topic structures in Wandora. It uses the open source JavaScript visualization library [http://d3js.org/ D3.js]. The service module's alias in Wandora is '''d3cloud''' and the URL of the visualization is

http://127.0.0.1:8898/d3/cloud

The visualization uses the currently open topic as a starting point and let's the user navigate through the topicmap by clicking on the cloud's words that map to associations of the current topic.

The visualization's layout can be modified with the following URL query string parameters:

<table>
<tr>
<td>font</td>
<td>Specifies the font used to render the words in the cloud</td>
</tr>
<tr>
<td>spiral</td>
<td>Specifies the spiral along witch the words are placed</td>
</tr>
<tr>
<td>scale</td>
<td>Specifies the function according to which the font sizes are calculated from the amount of associations that particular topic has.</td>
</tr>
<tr>
<td>from, to and or</td>
<td>the parameters for random rotation. "from" and "to" specify the range in degrees in relation to the vertical axis and "or" specifies the amount of steps within the range. For example from=-90&to=90&or=5 would result in each text's rotation to be randomly -90, -45, 0, 45 or 90 degrees</td>
</tr>
</table>

Also the parameter n can be used to limit the amount of topics retrieved from Wandora and thus the words rendered at a time.

A complete description of the parameters is provided on the visualization page and an example of their use follows below.

Note that as with D3 the browser support of D3 visualizations in Wandora is limited to IE9+ and up to date versions of Firefox, Chrome (+Chromium), Safari and Opera.

==Example==

The [[Topic_map_conversion_of_WordNet|WordNet]] is used to demonstrate the visualization

Selecting a topic in Wandora shows it and it's associatated topics in the browser.

[[Image:d3wordmap_01.png|center]]

[[Image:d3wordmap_02.png|center]]

font=times%20new%20roman is used to change the font of the cloud

[[Image:d3wordmap_03.png|center]]

from=-90&to=90&or=5 is further used to rotate the words randomly either -90, -45, 0 ,45 or 90 degrees

[[Image:d3wordmap_04.png|center]]

the cloud is navigated by clicking on the words as if they were links

[[Image:d3wordmap_05.png|center]]

A sense of completely random rotation is achieved by increasing the or-parameter

[[Image:d3wordmap_06.png|center]]

D3 word cloud service module

2014-05-16T09:51:12Z

Olli:

D3 graph service module

2014-05-16T09:50:49Z

Olli:

Wandora modules framework

2014-05-16T09:49:41Z

Olli: /* Embedded server */

Wandora contains a modular framework for setting up server applications. This can be used as part of a standard web app, or as a basis for a custom server application. It can also be used in the [[Embedded HTTP server]]. It could be used for other purposes than just server applications too but that is its primary purpose.

== Introduction ==

The idea behind the framework is that the server application consists of several individual modules, each of which does one specific thing. The modules often have dependencies between them, but some may also perform a completely isolated task.

As an example, a typical application might consist of the following modules:

* A topic map manager that provides a topic map for other modules and handles things related to the topic map.
* An Apache Velocity engine module which handles interfacing with Velocity.
* A template manager module which handles common tasks related to page templates.
* Several template modules, each representing one page template. These will register themselves to the template manager so other modules can find them, and use the Velocity Engine module to render the page. The templates could also be other than Velocity templates, but currently Velocity is the only supported template engine.
* A server module that receives HTTP requests and forwards them to other modules. Currently there are two options for this. One which interfaces a standard servlet container, such as Apache Tomcat, and one which interfaces with the [[Embedded HTTP server]].
* Several action modules, these are the logical entry points for outside users. They receive the requests from the server module and then process them. The action possibly does something on the server side and then gives back a result, typically by utilising one of the templates. Some of the action modules may utilise the topic map manager module to do something with the topic map it provides.

There are several other modules that an application could also utilise. Some examples are a database module which connects to a relational database, a module that sends email, modules that restrict access based on user authentication, and others.

Many of the modules work behind abstract interfaces with the idea that the implementation of a required module can easily be changed. The above list of modules already mentioned one such example: the two different options for the server module. Some others have been defined with an interface but currently there is only one implementation, like the templates. They could use any templating engine but currently Apache Velocity is the only supported one.

== Example web app ==

The ''samples/ModulesWebAppSample'' folder contains an example web app that can easily be deployed in Apache Tomcat or some other servlet container.

To use the sample web app, copy the entire folder into your ''webapps'' folder of the servlet container. Refer to the documentation of your servlet container on how to install web apps. Apache Tomcat at least has a folder called ''webapps'' directly under its installation folder where you just copy the entire ''ModulesWebAppSample'' folder. Then copy the compiled classes into the ''WEB-INF/classes'' folder inside the sample web app folder. To do this, just copy everything under Wandora's ''build/classes'' folder in there. The ''WEB-INF/lib'' folder should already contain the libraries needed by the sample web app, but if you add more functionality, you may need to copy more libraries here.

Next you may have to modify some configuration files. The ''WEB-INF/web.xml'' is the servlet configuration file, which is used by your servlet container to initialise the servlet. There's a section there that tells the servlet what modulesconfig.xml file to use to initialise the modules framework.

<init-param>
<param-name>modulesconfig</param-name>
<param-value>${catalina.base}/webapps/ModulesWebAppSample/WEB-INF/modulesconfig.xml</param-value>
</init-param>

Change the param-value if needed. If you copied the ''ModulesWebAppSample'' folder directly under your ''webapps'' folder, and you're using Apache Tomcat with more or less standard settings, you shouldn't need to change anything. Otherwise, set the absolute path to the modulesconfig.xml here. For more information about the ''web.xml'' file, refer to the servlet container documentation.

The ''WEB-INF/modulesconfig.xml'' file is the configuration file for the modules framework. This too should not require any editing if you have a basic Apache Tomcat setup. Otherwise, you may need to change some settings at the start of the file. The configuration file sets some variables, which may be referred to later using the syntax ''${variableName}''. The ''servletHome'' variable is preset by the servlet that loads this file. The configuration file section contains more information about the ''modulesconfig.xml'' file as a whole.

<variable key="home">${servletHome}</variable>
: This line sets the webapp home directory. It should point to the ''WEB-INF'' folder, with no slash or backslash at the end. The ''servletHome'' variable is preset by the servlet that loads this file and should work in most cases.
<variable key="port">8080</variable>
: This is the port number for the server.
<variable key="urlbase">http://localhost:${port}/ModulesWebAppSample/wandora</variable>
: This is the URL for the servlet.
<variable key="staticbase">http://localhost:${port}/ModulesWebAppSample/</variable>
: This is the base of the URL for the static content used by the webapp, such as the CSS file.
<variable key="topicMapFile">${home}/ArtofNoise.wpr</variable>
: This is the Wandora topic map project file to load. By default, it uses the Art of Noise sample topic map.
<variable key="defaultSI">http://www.wandora.org/mp3/mp3</variable>
: This is the subject identifier of the default topic, if nothing else is specified in the http request.

The rest of the ''modulesconfig.xml'' file should use the initial variables to set everything else and you shouldn't need to change anything for the basic sample web app. Naturally, if you wish to customise the sample, you may have to modify all the other modules as well.

You may have to restart your servlet container too. After that, you should be able to browse the topic map by going to [http://localhost:8080/ModulesWebAppSample/wandora http://localhost:8080/ModulesWebAppSample/wandora] or whatever you set as the ''urlbase'' of your web app.

== Example embedded server app ==

'''The embedded server is about to be changed. The entire old framework is being changed to the modules framework. The adapter module described here will become unnecessary in the next release. See the next section for information on how the server will work.'''

The [[Embedded HTTP server]] also contains a sample that uses the modules framework in the ''resources/server/modules'' folder. The ''modulesconfig.xml'' is almost identical to the web app sample, with the exception of some of the variables at start which are automatically set by Wandora. Also the topic map manager is Wandora itself instead of a manager that loads the topic map from a file.

To use this, you only need to start the embedded server in the ''Server'' menu inside Wandora, or click the little icon at the bottom right corner of the window. After that, go to [http://localhost:8898/modules/ http://localhost:8898/modules/] with your browser.

Note that the sample modules application looks and behaves exactly like the basic topic application, which as a whole is much simpler, consisting only of a single velocity template and not much else. As such, the sample modules application isn't terribly useful, but it could be extended into a much more complicated application.

A nice use case for using the modules framework in the embedded server would be real time topic map editing for a web app that is normally ran on a proper servlet container. With minimal changes to the ''modulesconfig.xml'' file, you can run the same system inside Wandora and immediately see all the changes you make into the topic map. Thus you can make changes to the topic map and immediately see what they would look like in the final website.

== Embedded server ==

'''The embedded server is about to be changed. The entire old framework is being changed to the modules framework. The adapter described in the previous section will become unnecessary, instead the entire server is based on the modules framework. However, these changed are not yet in the currently released version.'''

The [[Embedded HTTP server]] is based on the modules framework. The framework consists of a root module manager which loads module bundles from subdirectories. The root manager has its own xml configuration file at ''resources/server/baseconfig.xml'' which sets up the basic environment for the module bundles. Each module bundle is in its own subdirectory with its own ''config.xml'' configuration file and any other files it needs, such as templates, data files, and images and style sheets. The module bundles may import modules from the root manager so that they don't need to recreate all the commonly needed modules. The root manager also sets some variables relating to the child module bundle paths. But for the most part, each module bundle operates as a separate module collection, and most everything described on this page about modules and their configuration applies to module bundles too.

Importing modules is done using the ''<import>'' element. For example, using the following in the ''config.xml'' of a module bundle imports a ''VelocityEngineModule'' from the ''baseconfig.xml'' of the parent manager into the manager of the child bundle. After this, modules in the child bundle can use ''VelocityEngineModule'' in other modules. This should be placed on the same level as all the module definitions, not inside a module definition.

<import class="org.wandora.modules.servlet.VelocityEngineModule"></import>

Note that the class specified here must be the class used when looking for the module. This is usually an interface, rather than the implementation. The actual module imported will then be some module that implements the specified class. If you try to import using the actual implementing class, the module will not be found. Although, some modules may require other modules based on a specific implementation too, this depends on the module that is dependant on the other module.

== Configuration file ==

=== Basic structure ===

All the modules are defined in a configuration file, typically called ''modulesconfig.xml''. This is an XML file with a fairly simple structure. The root element is ''<options>'' and under it each module is listed in ''<module>'' elements. The ''<module>'' element contains the Java class name of the module, which must implement the ''Module'' interface. Parameters for the module can be provided as child elements of the ''<module>'' element in ''<param>'' elements. For example, the following includes two modules, with the latter one containing some initialisation parameters for the module.

<?xml version="1.0" encoding="UTF-8"?>
<options>
<module class="org.wandora.modules.LoggingModule"></module>

<module class="org.wandora.modules.topicmap.SimpleTopicMapManager">
<param key="topicMap">topicmap.wpr</param>
<param key="autoSave">true</param>
</module>
</options>

=== Module dependency solving ===

Some module may require other modules to be present. All the required modules must be included in the config file. Their order does not matter, the modules are automatically loaded in such an order that modules that require others are loaded after the modules they need. This also means that there cannot be cyclic dependencies between the modules, although there are ways to work around this.

Dependencies are solved automatically based on the required module class or interface. The config file just needs to contain a module of that class or one implementing, or extending, it. But in some cases there may be more than one valid option for the dependency and you need to specify which to use. There are two ways to solve this.

First, you may name modules and then explicitly specify which module to use. Specify the name of the module in a name attribute in the ''<module>'' element. Then in the module that needs to use the other module, add a child element ''<useService>'' which specifies the service. Like this:

<module class="org.wandora.modules.topicmap.SimpleTopicMapManager" '''name="tmmanager"'''>
<param key="topicMap">topicmap.wpr</param>
<param key="autoSave">true</param>
</module>
<module class="org.wandora.modules.topicmap.ViewTopicAction">
'''<useService service="org.wandora.modules.topicmap.TopicMapManager" value="tmmanager"></useService>'''
<param key="action">topic</param>
<param key="templateKey">viewtopic</param>
</module>

In the service attribute you must specify which service this relates to and then in the value attribute you specify the name of the module to use.

The second option to resolve the conflict is to specify a priority for the modules. You do this with a priority attribute in the ''<module>'' element. Each module by default has priority 0. A module with a higher priority will be chosen over a module with a lower priority in the automatic dependency solving. A module with a negative priority will never be automatically used, it can only be used by explicitly specifying so with the ''<useService>'' element as shown above. The ''<useService>'' will always override any priorities.

In the following example, the second topic map manager would not automatically be chosen for other modules. If any module wishes to use that, it must be explicitly specified with the ''<useService>'' element as shown above.

<module class="org.wandora.modules.topicmap.SimpleTopicMapManager">
<param key="topicMap">topicmap1.wpr</param>
<param key="autoSave">true</param>
</module>
<module class="org.wandora.modules.topicmap.SimpleTopicMapManager" '''priority="-1"'''>
<param key="topicMap">topicmap2.wpr</param>
</module>

Also, the modules themselves may employ other means to specify what to use. As an example, all ''Template'' modules register themselves to a ''TemplateManager''. Modules which need templates then don't depend directly on the ''Template'' module but instead on the ''TemplateManager'' which has its own mechanisms for getting the correct ''Template'' module.

=== Variables ===

You can specify variables directly under the root ''<options>'' element using a ''<variable>'' element.

<variable key="home">/webapp/webapphome</variable>

The variable needs a key, which is how it is referred to elsewhere, and a value. The key is specified in the key attribute and the value is the contents of the whole element. This variable can then be used elsewhere in the config file when you give parameters to modules or specify other variables. This is done using a dollar sign and curly brackets and writing the key of the variable in the curly brackets. You could specify another variable using the previous one like this.

<variable key="images">${home}/images</variable>

Similarly you can use the dollar and curly brackets inside ''<param>'' elements when specifying module parameters.

== List of high level modules ==

Below is a list of high level modules that are ready to use as is with short descriptions of what they do. The lower level abstract modules are described in the module development section and the user control modules in the user control section.

=== org.wandora.modules package ===

* DefaultReplacementsModule
: The replacements system is a much lighter option to a full template engine. It's a simple search and replace based system that can be used by other modules to make any of their string values dynamic. The ''AbstractAction'' automatically uses any replacement module it can find, with the ''DefaultReplacementsModule'' being the only current implementation.
* EmailModule
: This module provides email services for others. You the SMTP server and any relevant details in the parameters.
* GenericDatabaseInterface
: This module provides relational database services. It uses JDBC and as such supports a wide range of different database servers. The server details are specified in the parameters.
* LoggingModule
: This module provides logging services for other modules. You should always have a logging module included. Depending on how you use the modules framework, one might be automatically included outside the config file.
* NetAuthenticatorModule
: If your server tries to request a resource through http, and the request must be authenticated with a user and a password, you can use this to add an authenticator for it. Note that this is not user authentication for incoming requests, this is for providing login details for requests the server initiates to other servers.
* ScopedModuleManager
: This is a child module manager that is also a module and can thus be placed inside another module manager. This way you can load another collection of modules inside the parent module manager. The child module manager may import modules from the parent for use inside the child configuration.

=== org.wandora.modules.cache package ===

* DiskCacheModule
: This module provides caching services for other modules that may need them. The results of other modules may be cached on the disk to speed up identical requests in the future. Obviously this is not suitable for all kinds of modules but may be very beneficial in some cases.

=== org.wandora.modules.servlet package ===

This package modules related to responding to HTTP requests. These types of modules are called actions, each of them perform some kind of action and then returns the result.

* ChainedAction
: This module can be used to chain two or more other actions together so that they are executed in sequence in response to a single http request. Typically only one of the actions returns anything and the others cause side effects on the server side.
* GenericTemplateAction
: This is one of the most useful modules. It runs a template, at the time a Velocity template but in future it could be some other kind of template too, through a template engine and then returns the result of that. The template context is initialised with values specified in the config file, with optionally passing on values from the HTTP request as well. As such, in many cases you can use this action directly without any making your own version of it. Custom application logic can instead be performed using the objects passed to the template in the template context.
* ImageResizeAction
: This module can be used to resize images server side to fit specified dimensions. This way you can have a repository of original images which are then resized to smaller dimensions before sent to the client web browser. Several image profiles can be specified in the module parameters, each with different image dimensions. The images can optionally be also cropped to fit the dimensions and a watermark can be stamped on the image. A cache should be used with this module so that the resizing process is done only once per each image and image profile combination.
* RedirectAction
: This module can return an HTTP redirect code so as to redirect the browser to a different address.
* RequestForwarder
: This module forwards the HTTP requests to another address server side and then returns the result of this. This can be used if you have a service in the server internal network that is inaccessible from outside and you wish to expose it. You may want to place some usage restrictions as well in such a case.
* SendEmailAction
: This module can send email, using an ''EmailModule'', in response to an HTTP request. This module extends ''GenericTemplateAction'', the sent email is the result of the processed template. This action doesn't respond to the HTTP request in any way so you should chain this action with some other that does using the ''ChainedAction'' module.
* TemplateManager
: This module keeps track of all templates and gives them to other modules that need them.
* VelocityEngineModule
: This module provides the Apache Velocity engine used to process Velocity templates.
* VelocityTemplate
: This module specifies a single Velocity template. It automatically registers itself to the ''TemplateManager''. Other modules can request this template using the template key specified in parameters.

=== org.wandora.modules.topicmap package ===

* SimpleTopicMapManager
: This module provides a topic map for other modules to use. The topic map is loaded from a Wandora project file or an XTM file. The module can also automatically save the topic map, if it's being modified by other modules.
* ViewTopicAction
: This is a ''GenericTemplateAction'' which tailored for serving pages about topics. Among other things, it finds the needed topic based on the HTTP request parameters and adds it to the template context.
* WandoraTopicMapManager
: This is the other topic map manager. It connects to a running Wandora application and takes the topic map from there. Typically only used with the [[Embedded HTTP server]] which itself is running inside Wandora. This way, any modifications to the topic map in the Wandora application are immediately reflected in the server.

== Access control ==

Access control is implemented using action contexts, not to be confused with template contexts used with Velocity templates. Each action binds to a specific context and then falls under whatever access restrictions are specified for that context. Different type of restrictions are placed by different context implementations.

Each context actually implements the ''ServletModule'' interface and looks to other actions as if it's the module receiving the HTTP requests. And, in a way, it is, it's just receiving them from another similar module and doing something with the request in between. As such, you will need to make sure that each context module and each action module use the right ''ServletModule''. You do this by using priorities and/or explicitly specifying the module to use as described module dependency solving section. Typically you will want to give a high priority to the final context so that your actions automatically use that. Then use the explicit naming of modules for the contexts themselves. If different actions are to bind to different contexts, you will have to explicitly specify that in each action.

Many of the access control modules require a ''UserStore'' where details about access privileges are stored for all users. Currently there are three options for this.

* StaticUserStore
: This user store reads all user details from the config file itself and does not permit changing them. This is mostly meant for development as it's quick to setup and can then later be replaced with a more suitable solution.
* FileUserStore
: This module stores user details in a file in json format. The module permits changing users details and overwriting the existing file. This module should only really be used when the users are fairly static and there is a small number of them.
* DatabaseUserStore
: This module stores user details in a relational database and requires a database module to provide the database services.

Below is a list of other modules relating to access control. These modules are all in the package org.wandora.modules.usercontrol.

* GenericContext
: This is the base class for most other context modules, but you can also use it on its own. In particular, using the urlPrefix parameter, you can control which http requests are directed into this context based on the path of the request. You may also use the contextPath parameter to change the default path on the server the actions use. It defaults to the directory containing the server ''modulesconfig.xml'' but can be changed to, for example, a subdirectory of that using a GenericContext. Because GenericContext is the base class of most other contexts, you can use these features with other contexts as well.
* BasicUserAuthenticator
: This module is basic in the sense that it performs the authentication using the BASIC www authentication scheme and it is also basic in functionality. It stores the passwords of users in plain text so it should never be used in production environment, at least not when user details are collected from a large unspecified group of users. It may be suitable for situations where you have only one or a few users, as in a small group of administrators, that need to be authenticated, and the risks of storing passwords on the server in plain text is of no concern. Even then, you should encrypt the connection using https, otherwise your password will also be transmitted in plain text.
* FrequencyRestrictedContext
: This module places frequency restrictions on the context. A specific user can use the service only a certain number of times in a specific time span. As in, only 10 requests per minute, 1000 requests per month or something similar.
* RoleRestrictedContext
: This module only allows users with a specific role defined in their user details. Note that ''BasicUserAuthenticator'' can do a similar thing in the more common simple cases and you don't need a separate ''RoleRestrictedContext'' at all.
* SourceRestrictedContext
: This module only allows access from certain IP addresses.

In addition to the modules mentioned above, there is also a ''ChangeUserAction'' which can be used to change the properties or roles of a user.

== Module development ==

=== Module hierarchy ===

You can make your own modules by implementing the ''Module'' interface or extending one of the abstract classes partially implementing it. Obviously you will need extend a higher level class or implement a certain interface if you wish to make your class do a specific task in the framework. All actions need to derive from ''AbstractAction'' but there are also higher level options like ''GenericTemplateAction''. In fact ''GenericTemplateAction'' can even work without any extension if you place the application specific code in the template itself. Below is a list of the most common extension points. More details of specific methods can be found in the javadoc.

* Module
: The root interface of the module class hierarchy. This is the most generic option available. But in most cases you should instead extend the AbstractAction instead which has basic implementations of all the methods.
* AbstractModule
: This is the most generic of the abstract classes implementing Module. All methods of the Module interface are implemented, but they don't really do anything useful without overriding some methods or adding functionality in other ways.
* ScriptModule
: This is a direct extension of AbstractModule which provides some scripting features in the modulesconfig.xml file for the module. Modules deriving from this can have scripts specified in the config which are ran when the module is initialised, stopped or started. You may want derive your class from this instead of AbstractModule to get these features, even if you don't immediately plan to use them. They can later be used to add triggers when a module is started or stopped.
* ServletModule.RequestListener
: This is the interface for action classes that respond to http requests.
* AbstractAction
: This is an abstract class that implements the ServletModule.RequestListener interface and can thus respond to http requests. It also extends ScriptModule, and thus AbstractModule, so it has basic module implementation as well. This is basically the most generic abstract class to extend for action type modules.
* CachedAction
: This is a direct extension of AbstractAction and provides caching options for the action. If your action can benefit from having action results cached, you should consider extending this action. Caching can always be also turned off in the config even if you do extend from this class.
* GenericTemplateAction
: This is a direct extension of CachedAction and adds template handling. This class doesn't have any abstract methods and is useful on its own without any extensions. It will take an http request, use the template specified in the config with the context also specified in the config and then return the result of running the template through the template engine. If you only require minimal application logic which can be placed in the template, then you can just use this class directly instead of extending it. Otherwise extend the class and add some application logic and then add more things in the context if needed.

=== Module life-cycle ===

The instantiation, initialisation, starting, stopping and dependency resolution is all handled by the ''ModuleManager''. The first thing in the life-cycle of a module is it being instantiated with the parameterless constructor, which modules should have. It is possible to not have this constructor in a module, but then it cannot be instantiated by the module manager automatically, meaning that you cannot use it in the config file at all. You can still add it in the module manager in your own custom code.

The constructor should not perform any big operations. It is assumed that instantiating the module is a fast operation and practically cannot fail, i.e. it should not throw any exceptions. There are other points in the life-cycle of the module where more complicated initialisation should be done.

Next the ''init'' method of the module will be called. The init method is given the parameters specified in the config file. What should happen in the init method is to process the parameters, store them in internal fields if needed, and validate that their values are sensible. Nothing time consuming should be done here, or anything with permanent side effects. The ''init'' method of every module will be called, even if the module is never going to be started, so at this point you do not know if the module will ever actually be expected to do anything. However, you may throw a ''ModuleException'' to indicate that the initialisation failed. For example, if some required parameters were not provided or the values of the parameters aren't sensible.

Next method in the life-cycle is ''getDependencies''. In here you can specify what modules your module depends on. You do this by calling the ''requireModule'' method of the manager, which will immediately throw an exception if no suitable module is found. You can also use the ''optionalModule'' method to specify an optional dependency. This will not throw an exception if the needed module is missing, but if it exists, it makes sure that the needed module is started before your module. Note that the module dependencies may depend on initialisation parameters.

After the dependencies have been solved, modules can be started. The module manager will call the ''start'' method. This is the place where you can start executing the actual job of the module. The start method itself should not block for too long, so you should do any potentially time consuming tasks asynchronously.

Finally modules are stopped by calling the ''stop'' method. You should stop all threads spawned by your module, perform any cleaning up duties, dereference large data structures so that they may be garbage collected and return your module in a state where it can be started again with the ''start'' method, which may or may not happen.

Refer to the javadoc for more details on all the specific methods and their parameters.