Communardo Software GmbH, Kleiststraße 10 a, D-01129 Dresden
0800 1 255 255

Confluence Systemsprache wechseln mit CUTE

Während mei­ner täg­li­chen Arbeit mit Confluence stelle ich oft fest, dass ich man­che Funktionalitäten öfter benö­tige als andere. In die­sen Momenten wün­sche ich mir, dass diese Funktionen ein­fa­cher und schnel­ler erreich­bar sind. Dies gilt vor allem dann wenn der Klickpfad sehr lang ist. Einer die­ser Fälle ist das Umstellen der Confluence System Sprache mei­nes aktu­ell ange­mel­de­ten Benutzeraccounts.

Mit Hilfe von CUTE lässt sich diese Anforderung aller­dings schnell erfül­len. Zudem benö­tige ich hierzu keine Kenntnisse in der Confluence Plugin Entwicklung. Es reicht wenn ich mich mit Velocity, Javascript und CSS auskenne.

Schritt 1: Erstellen einer neuen Extension

Nachdem ich das CUTE Plugin über den Atlassian Marketplace auf mei­nem Confluence System instal­liert habe kann ich direkt los­le­gen. Über die glo­bale Administration > CUTE erscheint die Oberfläche des Werkzeugs. Hier wähle ich "Add Extension" und ver­gebe für meine Extension einen aus­sa­ge­kräf­ti­gen Namen und einen ein­deu­ti­gen Schlüssel.

Nachdem das erle­digt ist kann ich durch Klicken auf "Edit" mit der Arbeit an der Extension beginnen.

Schritt 2: Liste aller installierten Sprachen im Confluence erstellen

Als aller ers­tes benö­tige ich von Confluence die Information wel­che Sprachversionen über­haupt im System instal­liert sind. Hierzu stö­bere ich in der Atlassian Confluence API und finde auch prompt den LanguageManager wel­cher mir über seine Methode "getLanguages" alle instal­lier­ten Sprachversionen zur Verfügung stellt. Also erstelle ich in mei­ner Extension eine neue Template Ressource.

In die­ser kann ich nun mit HTML und Velocity eine belie­bige Struktur erstel­len wel­che dann auto­ma­tisch in jede Seite ver­steckt ein­ge­bun­den wird. Ich beschließe das die Liste der Sprachen am bes­ten in der glo­ba­len Navigationsleiste von Confluence auf­ge­ho­ben ist. Also schaue ich mir das bestehen­den glo­bale Confluence Menü an und baue des­sen Struktur für einen neuen Menüeintrag nach. Desweiteren hole ich mir den LanguageManager mit Hilfe des im Template ver­füg­ba­ren Dienstes "applicationService" und sei­ner Methode "getComponent":

#set($languageManager = $applicationService.getComponent("com.atlassian.confluence.languages.LanguageManager"))

Da Ich für den obers­ten Menüpunkt kei­nen Text ver­wen­den möchte, suche ich mir ein aus­sa­ge­kräf­ti­ges Logo und füge die­ses zur Extension hinzu. Unter dem hin­zu­ge­füg­ten Logo ist nun ein Pfad ein­ge­blen­det den ich ein­fach in mein Template über­neh­men kann.

Der fer­tige Template Code für meine Liste sieht dann so aus:

#set($languageManager = $applicationService.getComponent("com.atlassian.confluence.languages.LanguageManager"))
<div id="cutelanguagebox">
    <li id="cutelanguagemenuwrapper" class="normal ajs-menu-item">
        <a id="browse-cutelanguages-link" class="browse trigger ajs-menu-title" href="#">
            <span>
                <img id="cutelanguage-icon" src="@contextPath/plugins/cute/static/resource/communardo.language.switch/globe.png" >
            </span>
        </a>
        <div class="ajs-drop-down assistive cutelanguages" hidden="">
            <ul class="cutelanguagelist">
                #foreach( $language in $languageManager.languages )
                    <li>
                        <a href="#" class="cutelanguagelink" locale="$language.name" title="">
                            <span>$language.displayLanguage</span>
                        </a>
                    </li>
                #end
            </ul>
        </div>
    </li>
</div>

Schritt 3: Verschieben des Template Codes

Der Template Code ist nun auf jeder Seite (außer den Administrations Sichten) ein­ge­bun­den. Allerdings ist er ver­steckt und muss nun per Javascript an die ent­spre­chende Stelle ver­scho­ben wer­den. Also erstelle ich eine neue Javascript Ressource.

Da ich im Template Code meine Navigation mit der Id "cut­e­lan­gu­age­box" mar­kiert habe, kann ich diese nun ein­fach nach dem Laden der Seite in die glo­bale Navigation ein­fü­gen und anschlie­ßend das Menü neu initia­li­sie­ren damit alle Effekte wie­der pas­sen. Hier der Javascript Code:

AJS.toInit(function() {
    jQuery("#header-menu-bar").prepend( jQuery("#cutelanguagemenuwrapper"));

    //reinitialize menu after modification
    jQuery("#header-menu-bar *").unbind();
    jQuery("#header-menu-bar").ajsMenu({
        isFixedPosition : true
    });
});

Schritt 4: Ändern der Systemsprache

Das eigent­li­che Ändern der Systemsprache beim Klick auf einen der Menüeinträge geschieht durch Aufruf der glei­chen Action die auch beim nor­ma­len System Sprachenwechsel in der Profilkonfiguration Anwendung fin­det. Hierzu ver­wende ich wie­der eine neue Javascript Resource mit deren Hilfe ein AJAX Request beim Klick auf die Sprache im Hintergrund aus­ge­führt wird. Ist die­ser erfolg­reich, lade ich die Seite per Javascript neu. Hier der Code:

AJS.toInit(function() {
    jQuery("#cutelanguagemenuwrapper .cutelanguagelink").click( cuteChangeLanguage);
});

function cuteChangeLanguage() {
    jQuery.post(contextPath+"/users/doeditmysettings.action", {atl_token: jQuery("#atlassian-token").attr("content"), preferredUserLocale : jQuery(this).attr("locale")}, function(data){
        window.location.reload();
    });
    return false;
}

Schritt 5: Der Feinschliff

Das Ergebnis kann sich nun schon sehen las­sen. Allerdings ist das Icon zu groß für die obere Navigationsleiste. Hier muss also noch mit etwas CSS nach­ge­hol­fen wer­den. Ich füge eine neue Stylesheet Ressource hinzu.

In die­ser defi­niere ich nun einen Style wel­cher das obere Navigations-Icon auf eine ange­nehme Größe bringt. Hier das CSS:

#cutelanguage-icon {
    width: 20px;
    vertical-align: middle;
}

Das Ergebnis

Und fer­tig ist die Extension. Der neue Menüpunkt in der glo­ba­len Navigation fügt sich toll in den bestehen­den Style ein und funk­tio­niert auch mit den ande­ren Standard Themes (Documentation und EasyReader). Außerdem ist die Extension von Confluence 3.4 bis Confluence 4.2 kom­pa­ti­bel. Dies wird durch den mini­ma­len Eingriff am System gewähr­leis­tet. Die Chance der Kompatibilität zu neuen Confluence Versionen ist sehr hoch da kein Plugin ent­wi­ckelt wurde wel­ches zen­trale Confluence Templates überschreibt.

Die Extension selbst kann nun ein­fach expor­tiert und auf einem belie­bi­gen ande­ren Confluence System impor­tiert werden.

Baut es nach und macht es noch toller!

Ich habe die Extension in unse­rem Supportportal abge­legt damit jeder sie impor­tie­ren und auf sei­nem System edi­tie­ren kann. Sie ist ein guter Startpunkt für Extensions die in eine ähn­li­che Richtung gehen.

Related Posts

Pin It on Pinterest