mQuery - das in SharePoint integrierte jQuery

​Wer kennt es nicht? Für die einfache DOM-Manipulation mittels JavaScript wird gerne auf jQuery zurückgegriffen. Allerdings begegnet man im SharePoint Kontext bei der Verwendung dieser Library der einen oder anderen Herausforderung, wie ein Konflikt mit einer bereits durch einen anderen Anbieter eingebundenen jQuery Version, den richtigen Ablageort oder der schlichten Bequemlichkeit jQuery lediglich für eine H​andvoll an Manipulationen gegenüber purem JavaScript den Vortritt zu gewähren. An dieser Stelle eignet sich mQuery, ein bereits in SharePoint vorhandenes jQuery Derivat. Dieses umfasst zwar nicht den vollen Funktionsumfang von jQuery, lässt sich aber äquivalent anwenden und bedient den Bedarf an häufig verwendeten jQuery-Methoden. Überdies implementiert es Utility-Methoden, die etwa zur Überprüfung von JavaScript-Objekten auf bestimmte Typen oder Werte angewendet werden können.

Der Quellcode zu mQuery kann bspw. unter https://ncsky.sharepoint.com/_layouts/15/mquery.debug.js betrachtet werden.

Eine Einbindung erfolgt etwa mittels des folgenden Codeausschnittes, wodurch mQuery on demand geladen und vor dem Ausführen des eigenen Codes sichergestellt wird, dass diese korrekt geladen wurde.

    
    SP.SOD.executeFunc('mquery.js', 'm$', function() {
        //Mein mquery code
        m$('body').append('<div>Hallo novaCapta!</div>');
        m$('#MeineId').click(function() { console.log('I <3 mQuery'); });
    });
    
Wie der obige Codeausschnitt zeigt, wird eine mQuery-Methode auf ein mQuery-Objekt (m$()) ausgeführt. Ein mQuery-Objekt wird mittels m$(Selektor) äquivalent zur Verwendung in jQuery erzeugt.

Methoden:

mQuery stellt eine Vielzahl an Methoden zur Verfügung, die auf ein mQuery-Objekt ausgeführt werden können. Dabei kann ein mQuery-Objekt ein Element oder eine Menge an Elementen repräsentieren. Im Folgenden wird exemplarisch zur Vereinfachung das Verhalten der jeweiligen Methoden an einem einzelnen Element erläutert.

  • append(content)
    • Content kann Element, mQuery-Objekt oder HTML sein
  • bind(event name, handler)
    • Bindet ein Eventhandlerfunktion an das Element
  • unbind(event name, handler)
    • Entfernt ein Eventhandlerbinding
  • trigger(event name)
    • Löst ein bestimmtes Event auf dem Element aus
  • contains(selector)
    • Prüft, ob ein bestimmtes Element enthalten ist
  • detach
    • Entfernt einen Node aus der DOM
  • find(selector)
    • Gibt Kinderelemente des Elements zurück, auf die der Selektor zutrifft
  • closest(selector, context)
    • Gibt das nächst gelegene Element zurück, auf welches der Selektor zutrifft
    • Context ist optional (bspw. this)
  • offset (coordinates)
    • Gibt das Offset des Elements zurück
    • coordinates stellen einen optionalen Parameter dar. Wenn gesetzt fungiert dieser als Setter
  • one(event name, handler)
    • Bindet einen Eventhandler an das Element
  • filter(selector or function, handler)
    • Filtert eine Liste von Elementen anhand einer vorgegebenen Funktion, die true oder false für ein Element zurückliefert. Nur Elemente, für welche die Funktion true zurückliefert, landen in der Ergebnismenge.
  • not(selector, context)
    • Filtert ein Element, sofern es nicht auf den Selektor zutrifft
  • offsetParent(selector)
    • Gibt das Offset des übergeordneten Elementes zurück
  • parents(selector)
    • Gibt die direkt übergeordneten Elemente zurück
    • Wird ein Selektor angegeben, so beschränkt sich die Ergebnismenge auf entsprechend zutreffende übergeordnete Elemente
  • parentsUntil (element, filter)
    • Gibt Elemente bis zu einem bestimmten Element zurück
    • Sofern für den Parameter filter ein Selektor angegeben wurde, wird die Ergebnismenge gemäß .filter und des angegebenen Filterselektors gefiltert
  • position()
    • Gibt die Position des Elementes zurück
  • attr(attribute name, value)
    • Gibt ein Attribut zurück oder legt dieses fest
    • Der Parameter value ist optional. Wenn gesetzt fungiert diese Funktion als Setter
  • addClass(class names)
    • Fügt dem Element eine Klasse hinzu
  • removeClass(class names)
    • Entfernt eine Klasse des Elements
  • css(style name, value)
    • Gibt eine css-Eigenschaft zurück oder legt diese fest
    • z.B. css('color') oder css('color', 'red')
  • remove()
    • Entfernt das Element aus der DOM
  • children()
    • Liefert alle direkten untergeordneten Elemente des Elements zurück
  • empty()
    • Entfernt alle untergeordneten Elemente aus der DOM
  • first()
    • Gibt das erste Element einer Elementenmenge zurück
  • data(key, value)
    • greift auf m$.data() zu, welches wiederum den Zugriff auf ein internes data-Objekt regelt
  • removeData(key)
    • Entfernt eine Eigenschaft aus dem Datenobjekt
  • EventuallyDetect_DOMNodeRemovedFromDocument()
    • Gibt eine Funktion zurück, die einen handler als Parameter erwartet
    • Dieser handler wird für das Event „DOMNodeRemovedFromDocument" oder andernfalls wird überprüft, ob das Element noch existiert und ruft anschließend den handler auf

Eventhandler:

Die folgenden Eventhandler können für ein Element definiert werden. Dabei gibt der Funktionsname die Bezeichnung des ausgelösten Events und der Parameter handler die Eventhandlerfunktion an.

  • blur(handler)
  • click(handler)
  • change(handler)
  • dlick(handler)
  • dblclick(handler)
  • error(handler)
  • focus(handler)
  • focusin(handler)
  • focusout(handler)
  • keydown(handler)
  • keypress(handler)
  • keyup(handler)
  • load(handler)
  • mousedown(handler)
  • mouseenter(handler)
  • mouseleave(handler)
  • mousemove(handler)
  • mouseout(handler)
  • mouseover(handler)
  • mouseup(handler)
  • resize(handler)
  • scroll(handler)
  • select(handler)
  • submit(handler)
  • unload(handler)

Array Methoden:

  • indexOf(element, startIndex)
  • lastIndexOf(element, startIndex)

Array/ Objekt Methoden:

  • filter (function, context)
  • forEach(function, context)
  • every(function, context)
  • map(function, context)
  • some(function, context)

m$.-Methoden/ Utilities:

Ferner implementiert mQuery eine Vielzahl ein Utilitymethoden, die gängige Abfrage erleichtern sollen.

  • Prüfmethoden auf einen bestimmten Typ
    • m$.makeArray(object)
    • m$.isDefined(object)
    • m$.isNotNull(object)
    • m$.isUndefined(object)
    • m$.isNull(object)
    • m$.isUndefinedOrNull(object)
    • m$.isDefinedAndNotNull(object)
    • m$.isString(object)
    • m$.isBoolean(object)
    • m$.isFunction(object)
    • m$.isArray(object)
    • m$.isNode(object)
    • m$.isElement(object)
    • m$.isMQueryResultSet(object)
    • m$.isNumber(object)
    • m$.isObject(object)
    • m$.isEmptyObject(object)
  • Weitere Funktionalitäten
  • m$.throttle(function, interval, shouldOverrideThrottle)
    • Gibt eine Funktion zurück, welche die unter dem Parameter function angegebene Funktion nach einer zeitlichen Verzögerung wiederholt aufruft. Diese Verzögerung wird über den Parameter interval angegeben.
  • m$.extend(target Object, Object B, Object C, Object D, …)
    • Zusammenführen von mehreren Objekten in das erste Objekt (target Object)
  • m$.isReady(callback function)
  • m$.contains(container, element which is contained)
  • m$.proxy(function, context)
    • Führt eine Funktion unter einem anderen Kontext aus (z.B. um anstelle von this ein anderes Objekt innerhalb einer Funktion zu verwenden)
  • m$.every(object, function, context)
  • m$.filter(array or object or selector, function, context)
  • m$.forEach(object, function, context)
  • m$.indexOf(array, object, start index)
  • m$.lastIndexOf(array, object, start index)
  • m$.map(object, function, context)
  • m$.some(object, function, context)
  • m$.data(src, key, value)
  • m$.removeData(src, key)
  • m$.hasData(src)
​​

Comments