Quelltext der Seite Documentation/Project K/Import procedure

Virtual research environment for collaborative analysis of classroom photographies.
The initial metadata have been collected in Citavi system, which prones to errors and many cycles of data correction and validation.
Metadata collected in Citavi was exported first to an Excel file and after to xml format.

== Prerequisites ==

In order to have a meaningfull data, the following steps are necessary:
* Cleaning up the data. Please verify that MSWord text formatting characters are not into Citavi file. If yes, please remove them.
* Export Citavi file to Excel
* Build up a schema for Excel file. This will be used to export excel file to XML format. XML format will be transformed using an .XSLT transformation script.

An example of the schema file is the following:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="ItemsTable">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="ItemRow" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="ItemRow">
        <xs:complexType>
            <xs:sequence>
				<xs:element name="Jahrermittelt" type="xs:string"/>             
                <xs:element name="Titel" type="xs:string"/>
				<xs:element name="Dateiname_Artikel" type="xs:string"/>
				<xs:element name="Ort" type="xs:string"/>
				<xs:element name="Verlag" type="xs:string"/>
				<xs:element name="Zeitschrift_Zeitung" type="xs:string"/>
				<xs:element name="Nummer" type="xs:string"/>
				<xs:element name="Seiten_von_bis" type="xs:string"/>
				<xs:element name="Artikeltitel" type="xs:string"/>
				<xs:element name="Artikelseiten" type="xs:string"/>
				<xs:element name="Artikelautor" type="xs:string"/>
				<xs:element name="Fotoredaktion_Gestaltung" type="xs:string"/>
				<xs:element name="Fotountertitel" type="xs:string"/>
				<xs:element name="Jahrgang" type="xs:string"/>
				<xs:element name="Notiz" type="xs:string"/>
				<xs:element name="Rubrik" type="xs:string"/>
				<xs:element name="Redaktion" type="xs:string"/>
				<xs:element name="Autor" type="xs:string"/>
				<xs:element name="Fotoagentur" type="xs:string"/>
				<xs:element name="Kategorien" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

</pre>

Use the transformation procedure as it is described in: [https://blog.udemy.com/excel-to-xml/ Excel to XML: How to Transfer Your Spreadsheet Data Onto an XML File]


== Import requirements ==

Import procedure requires:
* a valid XML file, as result of the prequisites step. An example of this XML files:

<pre>
<?xml version="1.0" encoding="utf-8"?>
  <ItemsTable>
	<ItemRow ID="1">
		<Jahrermittelt>1988</Jahrermittelt>
		<Titel>Päd 1988.01_S46.1</Titel>
		<Dateiname_Artikel>Päd_1988.01_S46-51</Dateiname_Artikel>
		<Ort>Weinheim</Ort>
		<Verlag>Julius Beltz GmbH &amp; Co. KG</Verlag>
		<Zeitschrift_Zeitung>Pädagogik</Zeitschrift_Zeitung>
		<Nummer>1</Nummer>
		<Seiten_von_bis>46</Seiten_von_bis>
		<Artikeltitel>Schulformen verändern ihr Gesicht - Eine Einführung in die Serie von Klaus-Jürgen Tillmann</Artikeltitel>
		<Artikelseiten>46-51</Artikelseiten>
		<Artikelautor>Tillmann, Klaus-Jürgen</Artikelautor>
		<Fotoredaktion_Gestaltung/>
		<Fotountertitel/>
		<Jahrgang>40</Jahrgang>
		<Notiz/>
		<Rubrik>Serie</Rubrik>
		<Redaktion>Teske, Rita; Wolter, Katrin; Bastian, Johannes; Daschner, Peter; Gudjons, Herbert; Kalb, Peter E.; Tillmann, Klaus-Jürgen</Redaktion>
		<Autor>Losacker, Wolfgang</Autor>
		<Fotoagentur/>
		<Kategorien>Fachraum; Parallele Sitzreihen; Schüler; Einzelarbeit; Schüler arbeiten; Bücher; Arbeitsblätter-Hefte-Mappen; Schreib- und Zeichenutensilien; 0,25; Halbnahe; Vogelperspektive; Schwarz-Weiß; Bildserie</Kategorien>
	</ItemRow>
.......................
<ItemRow ID="1300">
		<Jahrermittelt>1959</Jahrermittelt>
		<Titel>WPB 1959.12_S528</Titel>
		<Dateiname_Artikel>WPB_1959.12_S525-530</Dateiname_Artikel>
		<Ort>Braunschweig</Ort>
		<Verlag>Georg Westermann</Verlag>
		<Zeitschrift_Zeitung>Westermanns Pädagogische Beiträge</Zeitschrift_Zeitung>
		<Nummer>12</Nummer>
		<Seiten_von_bis>528</Seiten_von_bis>
		<Artikeltitel>Das Klassenzimmer</Artikeltitel>
		<Artikelseiten>525-530</Artikelseiten>
		<Artikelautor>Otterstädt, Herbert</Artikelautor>
		<Fotoredaktion_Gestaltung/>
		<Fotountertitel>Abb. 5. Wandbehang: Baum mit Phantasieschmetterlingen</Fotountertitel>
		<Jahrgang>11</Jahrgang>
		<Notiz>Es findet sich keine Angabe zum Fotografen, es ist aber wahrscheinlich, dass der Artikelautor selbst die Fotos gemacht hat.</Notiz>
		<Rubrik/>
		<Redaktion>Schietzel, Carl; Sprenger, Hans; Wommelsdorff, Otto; Kern, Artur; Odenbach, Karl</Redaktion>
		<Autor/>
		<Fotoagentur/>
		<Kategorien>Klassenraum; 0,25; Halbtotale; Zentralperspektive; Schwarz-Weiß; Bildserie</Kategorien>
	</ItemRow>
  </ItemsTable>
</pre>


* a structure wiki page, for translating the categories into upper level categories. This page will be created by wiki admin into MediaWiki: namespace, '''MediaWiki:Structure'''.

Example:
<pre>
*Setting
**Klassenraum
**Fachraum
**Flur
**Außenbereich
**Bühne
**Außerschulischer Lernort
**Setting uneindeutig
*Raumanordnung
**Parallele Sitzreihen
**Gruppentische
**U-Form
**Stuhlkreis
**ohne relevantes Mobiliar
**Tischkreis
**Einzeltische
**U-Form mit Quertischen
**Lehrertisch
**Tafel
*Akteure
**Lehrer
**Schüler
**Einzelperson
**Personengruppe
*Sozialformen des Unterrichts
**Frontalunterricht
**Plenumsunterricht
**Gruppenarbeit
**Partnerarbeit
**Einzelarbeit
*Lehrer-, Schüleraktivität
**Schüler arbeiten
**Lehrervortrag
**Schülervortrag
**Schüler verfolgen Vortrag
**Lehrer-Schüler-Interaktion
*Lehr- und Lernmittel
**Bücher
**Arbeitsblätter-Hefte-Mappen
**Schreib- und Zeichenutensilien
**Mal- und Bastelutensilien
**Werkzeuge-Instrumente-Gefäße
**Werkstoffe
**sonstige Lernmittel
**Musikinstrumente
**Visualisierungsmedien
**Computer
**Lehr- und Lernmittel uneindeutig
*Bildgröße
**2
**1,5
**1
**0,75
**0,5
**0,33
**0,25
**0,125
*Einstellungsgröße
**Totale
**Halbtotale
**Halbnahe
**Nahe Einstellung
**Großaufnahme
**Detailansicht
*Perspektive
**Zentralperspektive
**Froschperspektive
**Vogelperspektive
*Schärfe als Kontrastmittel
**Schärfe als Kontrastmittel
*Farbe
**Farbe
**Schwarz-Weiß
*Bildserie
**Bildserie
</pre>

* a .XSLT transformation file, to transform XML file to wiki content using wiki templates. These templates have to be previously created into wiki.

== SMW extension for import ==

The extension '''ImportK''' is of type SpecialPage for MediaWiki. Requires:
* a valid MediaWiki installation, version 1.29.x or later.
* a valid Semantic MediaWiki installation, at least vesrion 2.5.4. For visualisation, Semantic Result Formats is also necessary. 
* other extensions: Parser Functions, Arrays, etc. 
* For how to install MediaWiki and extensions, please consult [https://www.mediawiki.org/wiki/MediaWiki MediaWiki] and [https://www.semantic-mediawiki.org/wiki/Semantic_MediaWiki  Semantic MediaWiki] sites.
* enables MediaWiki to upload pictures

=== Installation and Customization ===

'''IMPORTANT:''' For the http://doku-foto-unterrichtspraxis.semantic-cora.org/index.php/Hauptseite wiki, please skip the 1, 2 and 4. Create only the XML file, as in 3.

# download the extension from:
# install the extension as any other extensions of type SpecialPage for MediaWiki
# The valid XML file is in the extension root, under the name of '''exampl.xml'''. This can be changed too.
# edit LocalSettings.php file in order to set up the global variables, as follows:

<pre>
$ikFullImagePath = 'path to the pictures';
$ikFullLocalPath = 'valid path where the temporary wiki files will be stored'; // this folder has to be writable
$ikServerHostUrl = 'mediawiki root path';
$ikFilePrefix = 'Datei:'; // Might be 'File:' in other wikis
$ikCurrProject = "MediaWiki:Structure"; // other valid wiki page
</pre>

After the installation and set up, please check into wiki SpecialPages:Version or Spezial:Version, if the extensions is correctly installed. The extension is under the section '''Other special pages'''.

=== Usage ===

Call the extension under the '''SpecialPage:ImportK'''. A window will pop up, as in the picture:

[[File:ImportK.jpg]]

Fill in '''From index'''  and '''To index''' with a valid number, as in the example:

[[File:ImportK1.jpg]]


Check the '''Upload pictures too''' checkbox, if you want pictures to be uploaded. Else, only the metadata will be created. 

'''IMPORTANT:''' 
*If the XML file does not have a field that count the records, please add one using the '''addId.xsl''' that comes with extension distribution.
*Due to the browser connections time set ups, it is recommendable to not use more than 100 items per import session. Please notice that upload procedure is time consuming and have patience.

At the end of import session, a wiki page with log will be presented. If something went wrong, a message in red will be displayed.

=== Templates and entities ===

The extension creates the following entities as wiki classes and categories:

*Zeitschrift
*Heft 
*Article
*Foto 
*Person
*optional, Verlag


Each of the entities will be created via a separate template. 

*[[Template:Zeitschrift]]
*[[Template:Heft]]
*[[Template:Artikel]]
*[[Template:Foto]]
*[[Template:Person]]
*[[Template:Verlag]]

Additional, it might be useful to have [[Template:Verlag]] too.


[[Category:Documentation]]