Help:Contents import

From semantic-mediawiki.org
(Redirected from Help:Contents import)

This help page explains how the contents import is done with help of the "Importer" feature provided since Semantic MediaWiki 2.5.0Released on 14 March 2017 and compatible with MW 1.23.0 - 1.29.x..1 In short, import is done upon installation of Semantic MediaWiki from legitimate files located in the directory specified with configuration parameter $smwgImportFileDirsSets the contents import directory for legitimate files to be imported upon installation of Semantic MediaWiki which are available in the .json format (currently no other formats are supported) and contain the version specified with configuration parameter $smwgImportReqVersionSets the contents import file version for legitimate files to be imported upon installation of Semantic MediaWiki. After every import maintenance script "setupStore.php"Allows to set up the data backend/store has to be run.

Preselected import content is defined in the "vocabulary.json" file and includes "Smw import skos", "Smw import foaf", "Foaf:knows", "Foaf:name" and "Foaf:homepage".


The objective of the Importer is to provide a simple mechanism for deploying data structures and support information in a loose yet structured form during the installation (setup) process.

Import definitions

$smwgImportFileDirs defines import directories from where content can be imported.

Import definitions are defined using a JSON format which provides the structural means and is considered easily extendable by end-users.

The import files are sorted and therefore sequentially processed based on the file name. In case where content relies on other content an appropriate naming convention should be followed to ensure required definitions are imported in the expected order.

Default definitions

Preselected import content is defined in the "default.json" file and includes:

  • "Smw import skos"
  • "Smw import owl"
  • "Smw import foaf"
  • "Foaf:knows"
  • "Foaf:name" and
  • "Foaf:homepage"

It should be noted that default.json is not expected to be the authority source of content for a wiki and is the reason why the option canReplace is set false so that pre-existing content with the same name and namespace is not replaced.

Custom definitions

It is possible to define one or more custom import definitions using $smwgImportFileDirs with a custom location (directory) from where import definitions can be loaded.

$GLOBALS['smwgImportFileDirs']['movie-actor-vocab'] = __DIR__ . '/import/movie-actor';
$GLOBALS['smwgImportFileDirs']['custom-vocab'] = __DIR__ . '/custom';

Fields

JSON schema and fields:

  • description short description about the purpose of the import (used in the auto summary)
  • page the name of a page without a namespace prefix
  • namespace literal constant of the namespace of the content (e.g. NS_MAIN, SMW_NS_PROPERTY ... )
  • contents it contains either the raw text or a parameter
    • importFrom link to a file from where the raw text (contains a relative path to the $smwgImportFileDirs)
  • options
    • canReplace to indicate whether content is being allowed to be replaced during an import or not

The $smwgImportReqVersion stipulates the required version for an import and only definitions that match that version are permitted to be imported.

Examples

XML import

It is possible to use MediaWiki's XML format as import source when linked from the importFrom field (any non MediaWiki XML format will be ignored).

The location for the mentioned custom.xml is relative to the selected $smwgImportFileDirs directory.

{
    "description": "Custom import",
    "import": [
        {
            "description" : "Import of custom.xml that contains ...",
            "contents": {
                "importFrom": "/xml/custom.xml"
            }
        }
    ],
    "meta": {
        "version": "1"
    }
}
{
    "description": "Template import",
    "import": [
        {
            "description" : "Template to ...",
            "page": "Template_1",
            "namespace": "NS_TEMPLATE",
            "contents": "{{{1}}}, {{{2}}}",
            "options": {
                "canReplace": false
            }
        },
        {
            "description" : "Template with ...",
            "page": "Template_2",
            "namespace": "NS_TEMPLATE",
            "contents": {
                "importFrom": "/templates/template-1.tmpl"
            },
            "options": {
                "canReplace": false
            }
        }
    ],
    "meta": {
        "version": "1"
    }
}

Import process

During the setup process, the Installer will automatically run and inform about the process which will output something similar to:

Import of default.json ...
   ... replacing MediaWiki:Smw import foaf contents ...
   ... skipping Property:Foaf:knows, already exists ...

Import processing completed.

If not otherwise specified, content (a.k.a. pages) that pre-exists are going to be skipped by default.

Technical notes

SMW\Importer
│   └─ ContentCreators
│       ├─ DispatchingContentCreator
│       ├─ XmlContentCreator
│       └─ TextContentCreator
│
├─ ImporterServiceFactory # access to import services
├─ ContentIterator
├─ ContentCreator
├─ JsonContentIterator
├─ JsonImportContentsFileDirReader
└─ ContentModeller
  • SMW::SQLStore::Installer::AfterCreateTablesComplete provides the hook and is the event to execute the import during the setup
  • ImporterServiceFactory access to import services
  • Importer is responsible for importing contents provided by a ContentIterator
  • ContentIterator an interface to provide access to individual ImportContents instances
  • JsonContentIterator implements the ContentIterator interface
  • JsonImportContentsFileDirReader provides contents of all recursively fetched files from a location (e.g$smwgImportFileDirs setting ) that meets the requirements
  • ContentModeller interprets the JSON definition and returns a set of ImportContents instances
  • ContentCreator an interface to specify different creation methods (e.g. text, XML etc.)
  • DispatchingContentCreator dispatches to the actual content creation instance based on ImportContents::getContentType
  • XmlContentCreator support the creation of MediaWiki XML specific content
  • TextContentCreator support for raw wikitext

See also[edit]

References

  1. ^  Semantic MediaWiki: GitHub pull request gh:smw:2289