home.md

+## general info
+*  class API reference: https://doc.wikimedia.org/mediawiki-core/master/php/index.html
+
+## how to add a parser function
+
+### write the hook
+in `MathWikiAnnotationTags.class.php`:
+```
+public static function onParserSetup( &$parser ) {   
+   // Create a function hook associating the "example" magic word with renderExample()
+   $parser->setFunctionHook( 'annot', 'MathWikiAnnotationTags::renderStartAnnot' );
+   $parser->setFunctionHook( 'annotend', 'MathWikiAnnotationTags::renderEndAnnot' );
+}
+```
+
+### register the magic words: {{#annot}} and {{#annotend}}
+in `MathWikiAnnotationTags.i18n.php`:
+```
+$magicWords = array();
+$magicWords['en'] = array(
+   'annot' => array( 0, 'annot' ),
+   'annotend' => array( 0, 'annotend' ),
+);
+```
+
+### register the hook
+
+in `extension.json`:
+```
+"Hooks": {
+    "ParserFirstCallInit": [
+        "MathWikiAnnotationTags::onParserSetup"
+    ],
+    ...
+}
+```
+
+### register the extension in MediaWiki
+- place Folder of MyExtension into `/var/www/w/extensions`
+- or create a symbolic link: `ln -s /vagrant/MathWikiAnnotationTags/ MathWikiAnnotationTags`
+- edit `LocalSettings.php`
+   - add `wfLoadExtension( 'MathWikiAnnotationTags' );
+- or in MediaWiki vagrant, edit `settings.d/
+   - add a file `30-mathwiki.php`
+   - `<?php`
+   - `wfLoadExtension( 'MathWikiAnnotationTags' );`
+
+## how to create new tables in MediaWiki
+
+### create SQL file
+
+content of `MyExtension/sql/yata_annotation.sql`
+
+```
+BEGIN;
+--
+-- Tables for the YATA extension
+--
+
+-- Annotations table
+CREATE TABLE /*_*/yata_annotation (
+    -- unique identifier for every annotation
+    id int unsigned NOT NULL PRIMARY KEY AUTO_INCREMENT,
+    
+    -- the comment itself.
+    comment blob,
+    
+    -- the wiki text which is annotated
+    wiki_text blob,
+    
+    -- start and end position of the annotation according to the wiki sourcecode
+    start_char int unsigned,
+    end_char int unsigned,
+
+    -- foreign key to page.page_id
+    page_id int unsigned NOT NULL,
+
+    -- foreign key to user.user_id
+    user_id int unsigned NOT NULL,
+
+    -- foreign key to an annotation category
+    category_id int unsigned NOT NULL
+
+)/*$wgDBTableOptions*/;
+
+CREATE INDEX /*i*/yata_annot_page ON /*_*/yata_annotation (page_id);
+CREATE INDEX /*i*/yata_annot_user ON /*_*/yata_annotation (user_id);
+CREATE INDEX /*i*/yata_annot_category ON /*_*/yata_annotation (category_id);
+
+COMMIT;
+```
+
+### create function which invokes the SQL file
+
+in `MyExtension/Schema.php`: 
+
+```
+    public static function onLoadExtensionSchemaUpdates( DatabaseUpdater $updater ) {
+        $updater->addExtensionTable( 'yata_annotation', __DIR__ . '/sql/yata_annotation.sql');
+        $updater->addExtensionTable( 'yata_category', __DIR__ . '/sql/yata_category.sql');
+    }
+```
+Details see: https://www.mediawiki.org/wiki/Manual:Hooks/LoadExtensionSchemaUpdates
+
+### register Schema-update function
+
+in `extension.json`:
+
+```
+"AutoloadClasses": {
+    "MySchemaExtension": [
+        "Schema.php"
+    ]
+},
+"Hooks": {
+    "LoadExtensionSchemaUpdates": [
+        "MySchemaExtension::onLoadExtensionSchemaUpdates"
+    ]
+```
+
+### update the Schema
+
+- inside the Vagrant machine (`vagrant ssh`): `mwscript update.php`
+- in production:
+   - `cd mediawiki/maintenance`
+   - `./update.php`
+- details see https://www.mediawiki.org/wiki/Manual:Update.php
+
+
+## how to insert/update/select/delete data in tables
+
+- for write operations, you need to update the DB_MASTER
+```$dbw = wfGetDB( DB_MASTER );```
+
+- for reading operations, you get the DB_SLAVE. Never write here!
+```$dbr = wfGetDB( DB_SLAVE );```
+
+### insert
+```
+$dbw->insert(
+    'yata_annotation', 
+    array( 
+        wiki_text=>$content->getNativeData(), 
+        start_char=>0, 
+        end_char=>9999, 
+        page_id=>$wikiPage->getId(), 
+        user_id=>$user->getId() 
+    )  
+);
+```
+
+### select
+
+**select one single row only**
+```
+$row = $dbr->selectRow(
+    'yata_category',
+    array( 'id', 'name', 'description', 'parent_id' ),
+    array(
+        name => $category,
+        parent_id => $parent
+    )
+);
+$row->name;  # gets name field
+```
+
+**select more than one row, using a join operation**
+```
+$rows = $dbr->select( 
+    array(y1=>'yata_category', y2=>'yata_category'), 
+    array(  
+        id => 'y1.id',  
+        name => 'y1.name',  
+        description => 'y1.description', 
+        "parent" => 'y2.name', 
+        parent_id => 'y1.parent_id'  
+    ), 
+    array( 
+        'y1.name' => $category, 
+        'y2.name' => $parent 
+    ), 
+    __METHOD__, 
+    array(), 
+    array( 'y2' => array( 'INNER JOIN', array ( 'y1.parent_id = y2.id' ) ) ) 
+);
+foreach($rows as $row){
+    print($row->name);
+    print($row->description);
+}
+```
+
+### delete
+```
+$dbw->delete(
+    'yata_annotation',
+    array(
+        page_id=>$wikiPage->getId()
+    ) 
+);
+```
+Details see https://www.mediawiki.org/wiki/Manual:Database_access
+
+
+## How to alter source before save
+
+see https://stackoverflow.com/questions/32375120/automatically-add-text-content-to-mediawiki-short-pages
+
+### create onPageContentSave hook
+
+```
+public static function onPageContentSave(WikiPage &$wikiPage, User &$user, Content &$content, $summary, $isMinor, $isWatch, $section, $flags, Status &$status ){
+    $data = $content->getNativeData();
+    $data .= 'additional text';   # or any other source modification
+    $content = new WikitextContent( $data );
+}
+```
+
+### register the onPageContentSave hook
+
+```
+"Hooks": {
+    "PageContentSave": [
+        "MathWikiAnnotationTags::onPageContentSave"
+    ]
+}
+```