/ 
Quiq-1.219
River stage zero No dependents
/ Quiq::Confluence::Markup

NAME

Quiq::Confluence::Markup - Confluence-Wiki Markup

BASE CLASS

Quiq::Hash

DESCRIPTION

Ein Objekt der Klasse repräsentiert einen Generator für das Wiki-Markup von Confluence. Die Methoden der Klasse erzeugen dieses Markup, ohne dass man sich um die Details der Syntax kümmern muss.

Als Grundlage für die Implementierung dient die Confluence-Dokumentation:

Die Implementierung ist nicht vollständig, sondern wird nach Bedarf erweitert.

METHODS

Konstruktor

new() - Instantiiere Markup-Generator

Synopsis

$gen = $class->new;

Description

Instantiiere einen Confluence Wiki-Markup Generator und liefere eine Referenz auf dieses Objekt zurück.

Allgemeine Syntax

Synopsis

$markup = $gen->link($url);
$markup = $gen->link($url,$text);

Description

Confluence-Doku: Links

Erzeuge den Markup-Text für einen Link und liefere diesen zurück.

Examples

  • URL:

    $gen->link('https://confluence.atlassian.com/');

    erzeugt

    [https://confluence.atlassian.com/]

  • Text über URL:

    $gen->link('https://confluence.atlassian.com/','Atlassian');

    erzeugt

    [Atlassian|https://confluence.atlassian.com/]

paragraph() - Paragraph

Synopsis

$markup = $gen->paragraph($text);

Description

Erzeuge einen Paragraph und liefere den resultierenden Wiki-Code zurück. Ist $text nicht angegeben oder ein Leerstring, wird ein Leerstring geliefert. Andernfalls wird $text per trim() von einer etwaigen Einrückung befreit und Zeilenumbrüche durch Leerzeichen ersetzt, da ein Paragraph in Confluence-Wiki Syntax einzeilig ist.

Examples

  • Text:

    $gen->paragraph("Dies ist\nein Test.");

    erzeugt

    Dies ist ein Test.

  • Eine Einrückung wird automatisch entfernt:

    $gen->paragraph(q~
    Dies ist
    ein Test.
~);

    erzeugt

    Dies ist ein Test.

tableHeaderRow() - Tabellen-Kopfzeile

Synopsis

$markup = $gen->tableHeaderRow(@titles);

Description

Confluence-Doku: Tables

Erzeuge den Markup-Text für die Kopfzeile einer Tabelle und liefere diesen zurück.

Examples

  • Tabellen-Kopfzeile:

    $gen->tableHeaderRow(qw/A B C D/);

    erzeugt

    ||A||B||C||D||\n

  • Tabellen-Kopfzeile mit leerem Kolumnentitel:

    $gen->tableHeaderRow('A','','B','C','D');

    erzeugt

    ||A|| ||B||C||D||\n

tableRow() - Tabellen-Zeile

Synopsis

$markup = $gen->tableRow(@data);

Description

Confluence-Doku: Tables

Erzeuge den Markup-Text für die Zeile einer Tabelle und liefere diesen zurück.

Examples

  • Zeile:

    $gen->tableRow(1,2,3,4);

    erzeugt

    |1|2|3|4|\n

  • Zeile mit leerem Wert:

    $gen->tableRow(1,undef,2,3,4);

    erzeugt

    |1| |2|3|4\n

section() - Abschnitt

Synopsis

$markup = $gen->section($level,$title);
$markup = $gen->section($level,$title,$body);

Alias

heading()

Description

Confluence-Doku: Heading

Erzeuge einen Abschnitt der Ebene $level mit dem Titel $title und dem (optionalen) Abschnitts-Körper $body und liefere den resultierenden Code zurück. Ist $body nicht angegeben oder ein Leerstring, wird nur der Titel erzeugt. Andernfalls wird $body per trim() von einer etwaigen Einrückung befreit.

Examples

  • Ohne Body:

    $gen->section(1,'Test');

    erzeugt

    h1. Test

  • Mit Body:

    $gen->section(1,'Test',"Dies ist ein Test.");

    erzeugt

    h1. Test

Dies ist ein Test.

  • Eine Einrückung wird automatisch entfernt:

    $gen->section(1,'Test',q~
    Dies ist ein Test.
~);

    erzeugt

    h1. Test

Dies ist ein Test.

Macros

code() - Code-Block (code)

Synopsis

$markup = $gen->code($type,$code,@opts);

Options

-collapse => $bool (Confluence-Default: 0)

Zeige den Code-Block zusammengeklappt an. Durch Betätigung eines Link kann er aufgeklappt werden.

-firstLine => $n (Confluence-Default: 1)

Wenn Option -lineNumbers gesetzt ist, die Nummer der ersten Zeile, ggf. mit führenden Nullen. Z.B. 0001.

-lineNumbers => $bool (Confluence-Default: 0)

Nummeriere die Zeilen durch.

-theme => $theme (Confluence-Default: 'Confluence')

Das Farbschema für die Darstellungs des Code-Blocks. Mögliche Werte siehe o.g. Confluence-Doku.

-title => $title (Confluence-Default: kein Titel)

Füge einen Titel zum Code-Block hinzu.

Description

Confluence Doku: Code Block Macro

Erzeuge ein Code-Macro für Code $code mit Syntax-Typ $type und liefere den resultierenden Wiki-Code zurück. Die Liste der verfügbaren Syntax-Typen findet sich in o.g. Confluence-Doku.

Examples

  • Ein eingeklappter Code-Block:

    $gen->code('perl',"print 'Hello, world!';",
    -collapse => 1,
);

    erzeugt

    {code:language=perl|collapse=true}
print 'Hello, world!';
{code}

noFormat() - Text-Block ohne Formatierung (noformat)

Synopsis

$markup = $gen->noFormat($text,@opts);

Options

-noPanel => $bool (Confluence-Default: 0)

Kein Panel um den Inhalt herum.

Description

Confluence Doku: Noformat Macro

Zeige einen Text-Block monospaced ohne weitere Formatierung an.

Anmerkung: Dieses Makro ist nicht geeignet, um eine Formatierung innerhalb eines Paragraphen zu verhindern, da der Text als eigenständiger Block (mit oder ohne Umrandung) dargestellt wird. Es entspricht einem Code-Block-Makro ohne Syntax-Highlighting, bei dem zusätzlich die Umrandung unterdrückt werden kann.

Examples

  • Anzeige eines regulären Ausdrucks:

    $gen->noFormat('m|/([^/]+)xxx{5}$|',
    -noPanel => 1,
);

    erzeugt

    {noformat:nopanel=true}m|/([^/]+)xxx{5}$|{noformat}

panel() - Umrandung mit optionalem Titel (panel)

Synopsis

$markup = $gen->panel($body,@opts);

Options

-title => $title (Confluence-Default: none)

Titel des Panel.

-borderStyle => $style (Confluence-Default: 'solid')

Stil der Umrandung. Wert: solid, dashed und andere CSS Umrandungs-Stile.

-borderColor => $color

Farbe der Umrandung. Wert: wie HTML.

-borderWidth => $n

Breite der Umrandung in Pixeln.

-backgroundColor => $color.

Hintergrundfarbe. Wert: wie HTML.

-titleBackgroundColor => $color

Farbe Titel-Hintergrund. Wert: wie HTML.

-titleTextColor => $color

Farbe des Titel-Textes. Wert: wie HTML.

Description

Confluence-Doku: Panel Macro

Erzeuge ein Panel-Macro mit Inhalt $body und liefere den resultierenden Wiki-Code zurück.

tableOfContents() - Inhaltsverzeichnis (toc)

Synopsis

$markup = $gen->tableOfContents(@opts);

Options

-type => 'list'|'flat' (Confluence-Default: 'list')

Listenartiges oder horizontales Menü.

-outline => $bool (Confluence-Default: 0)

Outline-Numbering ((1.1, 1.2, usw.) aus oder ein.

-style => $style (Confluence-Default: 'disc')

Style der Bullet-Points. Wert: Wie CSS (none, circle, disc, square, decimal, lower-alpha, lower-roman, upper-roman).

-indent => $indent

Einrücktiefe zwischen den Ebenen (nur Liste). Wert: CSS-Einheit (z.B. 10px).

-separator => $separator (Confluence-Default: 'brackets')

Separator bei horizontalem Inhaltsverzeichnis: Wert: brackets, braces, parens, pipe, anything.

-minLevel => $n (Confluence-Default: 1)

Die niedrigste Ebene, die in das Inhaltsverzeichnis aufgenommen wird.

-maxLevel => $n (Confluence-Default: 7)

Die höchste Ebene, die in das Inhaltsverzeichnis aufgenommen wird.

-include => $regex

Regulärer Ausdruck, der die Abschnittstitel matcht, die in das Inhaltsverzweichnis aufgenommen werden.

-exclude => $regex

Regulärer Ausdruck, der die Abschnittstitel matcht, die nicht in das Inhaltsverzweichnis aufgenommen werden.

-printable => $bool (Confluence-Default: 1)

Das Inhaltsverzeichnis wird mit ausgegeben, wenn die Seite gedruckt wird.

-class => $class

Inhaltsverzeichnis wird in <div class="$class">...</div> eingefasst.

-absoluteUrl => $bool

Verwende absolute URLs.

Description

Confluence-Doku: Table of Contents Macro

Erzeuge ein Inhaltsverzeichnis-Macro und liefere den resultierenden Wiki-Code zurück.

Text-Formatierung

fmt() - Text-Formatierung

Synopsis

$str = $this->fmt($format,$text);
$str = $this->fmt($color,$text);

Description

Confluence-Doku: Text Effects

Erzeuge Formatierung $format für Text $text und liefere den resultierenden Wiki-Code zurück.

Es existieren die Formatierungen:

  • bold

  • italic

  • citation

  • deleted

  • inserted

  • superscript

  • subscript

  • monospace

  • blockquote

  • $color

  • protect

Das Format 'protect' ist eine Erweiterung der Confluence-Formatierungen. Es schützt die Zeichen in $text, so dass diese formatierungsfrei dargestellt werden. Geschützt werden die Zeichen:

- * _ + ^ ~ [ ] { }

Die Interpretation als Metazeichen wird durch das Voranstellen eines Backslash (\) verhindert.

lineBreak() - Zeilenumbruch

Synopsis

$str = $gen->lineBreak;

Test

testPage() - Generiere Test-Seite

Synopsis

$str = $this->testPage;

Description

Generiere eine Seite mit Wiki-Markup. Das Markup kann nach Confluence übertragen und dort optisch begutachtet werden.

Examples

  • Test-Seite von der Kommandozeile ins Wiki übertragen:

    $ quiq-confluence test-page | quiq-confluence update-page PAGE_ID

  • Manuelle Übertragung:

    1. Markup generieren:

      $ quiq-confluence test-page

    2. In Confluence die Zielseite zum Editieren öffnen und Option "Markup {}" wählen. Ausgabe aus 1. per copy-and-paste in den Dialog übertragen und diesen speichern.

VERSION

1.219

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.