Communardo Software GmbH, Kleiststraße 10 a, D-01129 Dresden
+49 (0) 351/850 33-0

Confluence Systemsprache wechseln mit CUTE

Während meiner täglichen Arbeit mit Confluence stelle ich oft fest, dass ich manche Funktionalitäten öfter benötige als andere. In diesen Momenten wünsche ich mir, dass diese Funktionen einfacher und schneller erreichbar sind. Dies gilt vor allem dann wenn der Klickpfad sehr lang ist. Einer dieser Fälle ist das Umstellen der Confluence System Sprache meines aktuell angemeldeten Benutzeraccounts.

Mit Hilfe von CUTE lässt sich diese Anforderung allerdings schnell erfüllen. 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 meinem Confluence System installiert habe kann ich direkt loslegen. Über die globale Administration > CUTE erscheint die Oberfläche des Werkzeugs. Hier wähle ich „Add Extension“ und vergebe für meine Extension einen aussagekräftigen Namen und einen eindeutigen Schlüssel.

Nachdem das erledigt 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 erstes benötige ich von Confluence die Information welche Sprachversionen überhaupt im System installiert sind. Hierzu stöbere ich in der Atlassian Confluence API und finde auch prompt den LanguageManager welcher mir über seine Methode „getLanguages“ alle installierten Sprachversionen zur Verfügung stellt. Also erstelle ich in meiner Extension eine neue Template Ressource.

In dieser kann ich nun mit HTML und Velocity eine beliebige Struktur erstellen welche dann automatisch in jede Seite versteckt eingebunden wird. Ich beschließe das die Liste der Sprachen am besten in der globalen Navigationsleiste von Confluence aufgehoben ist. Also schaue ich mir das bestehenden globale Confluence Menü an und baue dessen Struktur für einen neuen Menüeintrag nach. Desweiteren hole ich mir den LanguageManager mit Hilfe des im Template verfügbaren Dienstes „applicationService“ und seiner Methode „getComponent“:

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

Da Ich für den obersten Menüpunkt keinen Text verwenden möchte, suche ich mir ein aussagekräftiges Logo und füge dieses zur Extension hinzu. Unter dem hinzugefügten Logo ist nun ein Pfad eingeblendet den ich einfach in mein Template übernehmen kann.

Der fertige 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) eingebunden. Allerdings ist er versteckt und muss nun per Javascript an die entsprechende Stelle verschoben werden. Also erstelle ich eine neue Javascript Ressource.

Da ich im Template Code meine Navigation mit der Id „cutelanguagebox“ markiert habe, kann ich diese nun einfach nach dem Laden der Seite in die globale Navigation einfügen und anschließend das Menü neu initialisieren damit alle Effekte wieder passen. 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 eigentliche Ändern der Systemsprache beim Klick auf einen der Menüeinträge geschieht durch Aufruf der gleichen Action die auch beim normalen System Sprachenwechsel in der Profilkonfiguration Anwendung findet. Hierzu verwende ich wieder eine neue Javascript Resource mit deren Hilfe ein AJAX Request beim Klick auf die Sprache im Hintergrund ausgeführt wird. Ist dieser erfolgreich, 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 lassen. Allerdings ist das Icon zu groß für die obere Navigationsleiste. Hier muss also noch mit etwas CSS nachgeholfen werden. Ich füge eine neue Stylesheet Ressource hinzu.

In dieser definiere ich nun einen Style welcher das obere Navigations-Icon auf eine angenehme Größe bringt. Hier das CSS:

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

Das Ergebnis

Und fertig ist die Extension. Der neue Menüpunkt in der globalen Navigation fügt sich toll in den bestehenden Style ein und funktioniert auch mit den anderen Standard Themes (Documentation und EasyReader). Außerdem ist die Extension von Confluence 3.4 bis Confluence 4.2 kompatibel. Dies wird durch den minimalen Eingriff am System gewährleistet. Die Chance der Kompatibilität zu neuen Confluence Versionen ist sehr hoch da kein Plugin entwickelt wurde welches zentrale Confluence Templates überschreibt.

Die Extension selbst kann nun einfach exportiert und auf einem beliebigen anderen Confluence System importiert werden.

Baut es nach und macht es noch toller!

Ich habe die Extension in unserem Supportportal abgelegt damit jeder sie importieren und auf seinem System editieren kann. Sie ist ein guter Startpunkt für Extensions die in eine ähnliche Richtung gehen.

Kommentar hinterlassen


Pin It on Pinterest