Die Allowed-Flags werden der Klasse FrameAPI im Konstruktor oder in setAllowed übergeben und regeln, welche Informationen diese Klasse an die Parent-Seite sendet. Dabei ist jede erlaubte Information ein bestimmtes, auf 1 gesetztes Bit. In der folgenden Tabelle stehen die 2er-Exponenten dieser Bits und was diese Bedeuten:
| 1 | signalisieren, dass die Seite FrameAPI anbietet und welche der folgenden Informationen gesendet werden sollen |
| 2 | Mauskoordinaten übertragen (nur Wirksam in Kombination mit 8 oder 16) |
| 4 | Click übertragen |
| 8 | Mousedown übertragen |
| 16 | Mouseup übertragen |
| 32 | Content-Höhe übertragen |
| 64 | Content-Breit übertragen |
| 128 | URL übertragen |
| 256 | Title übertragen |
| 512 | Mausrad + Wheeldelta übertragen |
Falls Sie nicht mein frameCommunicator.js verwenden wollen, aber ebenfalls die gleichen Befehle für postMessage verwenden möchten, zur besseren, allgemeinen Kompatibilität, habe ich hier die von mir benutzten Befehle aufgelistet:
| window.fapi | Globale Variable: Speichert die Instanz von FrameAPI, die automatisch von frameCommunicator.js erzeugt wird. | |||||||||||||||||||||||||||
| fapiStandard | Globale Variable: Speichert die Allowed-Flags, die als Default-Wert verwendet werden sollen (Standard 41). | |||||||||||||||||||||||||||
| getHostnameAndProtocol |
Erwartet eine URL, gibt den Anfang dieser URL bis einschließlich dem Hostname zurück. Online soll dies die entscheidende Information sein, ob die Same-Origin-Policy bei dieser
URL greift. Aber auch lokal soll, je nach URL, ein bestimmter Teil abgeschnitten werden. Der erste, nicht mehr zu Protocol/Hostname gehörende Buchstabe ist der erste, allein stehende Slash,
oder das erste ? oder das erste #. Parameter:
|
|||||||||||||||||||||||||||
| absolutePath |
Macht aus einem möglicher Weise relativen Pfad einen Absoluten. Als zweiter Parameter kann (optional) ein absoluter Pfad angegeben werden, von dem aus der Relative gelten soll. Parameter:
self.location.href := http://www.example.de/Ordner/Seite.html
|
|||||||||||||||||||||||||||
| relativePath |
Gibt (falls möglich) eine relative Variante eines absoluten oder zu root relativen Pfades zurück. Als zweiter Parameter kann (optional) ein absoluter Pfad angegeben werden, von dem aus der
Relative gelten soll. Parameter:
self.location.href := http://www.example.de/Ordner/Seite.html
|
|||||||||||||||||||||||||||
| createScrollRectEventListener |
Erstellt einen speziellen EventListener, der nach erstellen, sowie nach jeder Änderung der Seiten-/Elementhöhe, eine callback-Funktion aufruft, welcher die aktuelle Höhe (ScrollHeight)
und Breite (ScrollWidth) der Seite bzw. des gegebenen Elements übergeben werden. Motivation: Wenn eine Seite in einem IFrame dargestellt wird, ist es oft erwünscht, dass die Höhe dieses IFrames auf die Höhe der darin befindlichen Seite eingestellt wird. Jedoch habe ich festgestellt, dass es alles andere als trivial ist, die korrekte Höhe der Seite zu messen und erst recht nicht, auf Änderungen der selbigen zu reagieren. Es gibt verschiedene ECMA-Script Funktionen, die versprechen, die Höhe der Seite zu messen (z.B. scrollHeight, clientHeight, offsetHeight, boundingRect). Jedoch musste ich feststellen, dass diese je nach Browser vollkommen unterschiedlich reagieren. In Webkit und IE erzielt keine der Funktionen das erwünschte Ergebnis. Zwar gibt scrollHeight im Iframe immer die korrekte Höhe des Scrollbereiches zurück, jedoch ist dieser mindestens so hoch, wie der Iframe selbst. Soll heißen: Hat man ein mal die Höhe des Frames auf document.documentElement.scrollHeight gesetzt, und die Seite wird danach wieder kleiner, so bleibt scrollHeight trotzdem auf dem gesetzten Maximalwert stehen. Um nun aber die eigentlich erforderliche Mindesthöhe zu ermitteln, hilft alles nichts: Man muss am Ende des Inline-Contents ein Element einfügen, mit der CSS-Eigenschaft clear:both und da dieses im Falle absolut positionierter Elemente nicht funktionierten wird, zusätzlich über alle Child-Elemente von document.body iterieren, um ggf. ein absolut positioniertes Element zu finden, das die Scrollhöhe festlegt. createScrollRectEventListener setzt nun unterschiedliche Fallunterscheidungen und Heuristiken ein, um mit möglichst wenig CPU-Aufwand auch ein "Kleiner-Werden" der Seite zu erkennen. Dabei ist zu beachten, dass unter Umständen ein solches Höhenmesser-Element in Form einer unsichtbaren HR-Linie am Ende des body-Tags eingefügt wird. Um den erzeugten EventListener zu löschen, muss die Free-Funktion des zurrückgegebenen Objekts aufgerufen werden. Parameter:
|
Die Klasse FrameCommunicator kann für einen IFrame im Dokument erstellt werden. Ihr Konstruktor erwartet dieses IFrame als Parameter. Dabei wird der IFrame um die Eigenschaft communicator erweitert, welche eine Referenz auf die FrameCommunikator-Instanz ist. Mausevents, die mit FrameCommunicator übertragen werden, werden direkt vom Iframe-Element abgefeuert.
Eigenschaften von FrameCommunicator:| el | Speichert den Iframe, der im Konstruktor übergeben wird. |
| currentLoc | Speichert das letzte, bekannte Location-Objekt der Frame-Seite. Unterscheidet sich dieses von der aktuellen Seite, so muss die aktuelle Seite eine andere sein, als die, von der currentLoc stammt. Somit wird currentLoc für die Identifizierung der Frame-Seite benutzt. Identifizieren bedeutet hier, zu überprüfen, ob die Seite im Frame noch die gleiche ist, wie bei der letzten Ermittlung von currentLoc. CurrentLoc kann nur ermittelt werden, wenn die Frame-Seite von der gleichen Domain stammt. |
| currentPostMsg | Dient, genau wie currentLoc zur Identifizierung der Frame-Seite. Dabei wird nicht das Location-Objekt, sondern die PostMessage-Funktion der Seite gespeichert. Der Vorteil hier ist, dass PostMessage auch ermittelt werden kann, wenn die Frame-Seite von einer anderen Domain kommt. Jedoch funktioniert dieser Trick nicht in allen Browsern. |
| resizeRepeatH |
Wird mit jedem Aufruf von resize inkrementiert, aber erst nach 100ms, in denen kein Resize eingegangen ist, wieder auf 0 gesetzt. Motivation: Wird die Höhe des Iframes auf die Höhe der Frame-Seite gesetzt, kann dies auch die ScrollHeight der Frame-Seite beeinflussen. FrameAPI würde dann wieder ein Resize auslösen. Je nach Aufbau der Seite und Webbrowser kann dies zu einer Endlosschleife führen. Hat resizeRepeatH einen gewissen Wert überschritten, ist davon auszugehen, dass eine solche Rekursion auftritt und das Resize wird abgebrochen. Zu beachten ist, dass der Timer, der resizeRepeatH zurücksetzt, länger warten muss, als der pauseTimer von createScrollRectEventListener. |
| resizeRepeatW | Wie resizeRepeatH, nur für die Breite und nicht für die Höhe. Diese Unterscheidung ist wichtig, da nicht immer Breite und Höhe gleichzeitig gesendet, bzw. gesetzt werden. |
| siteAllows | Speichert die allowed-Flags die die Frame-Seite gesendet hat. Wenn die Seite ein Event schickt, das zu einem Flag gehört, so wird dieses auf 1 gesetzt, auch wenn die Seite keine Flags gesendet hat, oder signalisiert, dass dieses Flag 0 ist. |
| contentHeight | Speichert die Höhe des Inhaltes der Frame-Seite (-1, falls unbekannt). Beachten Sie: Seiten, die nicht das FrameAPI aus diesem Script verwenden, werden mit hoher Wahrscheinlichkeit nicht immer ihre richtige Höhe feststellen können, da dies relativ kompliziert ist. |
| contentWidth | Speichert die Breite des Inhaltes der Frame-Seite (-1, falls unbekannt) |
| contentHostname | Speichert den Hostname der Frame-Seite. Dieser wird automatisch mit onmessage übertragen. Die Frame-Seite kann an dieser Stelle also nicht "mogeln". Falls keine Message gesendet wurde, ist der Hostname unbekannt (''). |
| contentURL | Speichert die vollständoge URL der Frame-Seite ('', falls unbekannt). Der Anfang der URL muss mit contentHostname übereinstimmen. |
| contentTitle | Speichert den Titel der Frame-Seite ('', falls unbekannt) |
| onContentResize | Für diesen Wert kann eine Callback-Funktion eingesetzt werden, die immer dann ausgerufen wird, wenn die Frame-Seite eine neue Höhen-/Breitenangabe sendet. |
| onSiteReady | Für diesen Wert kann eine Callback-Funktion eingesetzt werden, die beim laden einer neuen Frame-Seite aufgerufen wird. onSiteReady ist im Prinzip wie iframe.onload, löst ggf. aber schon während dem Parsen der Frame-Seite aus. |
| onURLChanged | Für diesen Wert kann eine Callback-Funktion eingesetzt werden, die immer dann aufgerufen wird, wenn die Frame-Seite eine neue URL sendet oder ein neuer Hostname bekannt wird. |
| onTitleChanged | Für diesen Wert kann eine Callback-Funktion eingesetzt werden, die immer dann aufgerufen wird, wenn die Frame-Seite einen neuen Titel sendet. |
| autoHeight | Wenn true wird die Höhe des Iframes automatisch auf die Höhe der Frame-Seite gesetzt, wenn false, wird die Höhe des Iframes auf den Wert von autoHeightValue gesetzt. |
| autoWidth | Wenn true wird die Breite des Iframes automatisch auf die Breite der Frame-Seite gesetzt, wenn false, wird die Breite des Iframes auf den Wert von autoWidthValue gesetzt. |
| autoHeightValue | CSS-Style: Höhe des Iframes, falls autoHeight false. |
| autoWidthValue | CSS-Style: Breite des Iframes, falls autoWidth false. |
| checkForNewSite |
Prüft, ob die Seite im Frame sich geändert hat. Wenn ja, wird newSeite aufgerufen.
|
| newSite | Soll immer dann aufgerufen werden, wenn im Iframe eine neue Seite erkannt wurde. Löscht alle bekannten Informationen über die alte Seite und versucht, eine Instanz von FrameAPI in der neuen Seite zu erzeugen. |
| checkForNewHostname |
Aktualisiert den contentHostname. Sobald die Frme-Seite eine Nachricht schickt, ist dieser über onMessage:origin bekannt.
|
| interpretMessage |
Dies ist die Listener-Funktion für window.onmessage.
|
| raiseMouseEvent |
Feuert ein Mausevent vom Iframe-Element aus ab. Dadurch wird die Kompatibilität zu DOM verbessert: Andere Scripte müssen FrameCommunicator nicht kennen,
um z.B. Mausklicks auf den Frame zu erkennen. Kann bei gleicher Domain auch direkt von FrameAPI aufgerufen werden.
|
| setState |
Wird aufgerufen, wenn die Frame-Seite ihre Allowed-Flags sendet. Kann bei gleicher Domain auch direkt von FrameAPI aufgerufen werden.
|
| resize |
Wird aufgerufen, wenn die Frame-Seite eine neue Höhe oder Breite sendet. Kann bei gleicher Domain auch direkt von FrameAPI aufgerufen werden.
|
| newURL |
Wird aufgerufen, wenn die Frame-Seite ihre URL sendet. Kann bei gleicher Domain auch direkt von FrameAPI aufgerufen werden.
|
| setTitle |
Wird aufgerufen, wenn die Frame-Seite ihren Titel sendet. Kann bei gleicher Domain auch direkt von FrameAPI aufgerufen werden.
|
Die Klasse FrameAPI wird automatisch beim laden der Seite erstellt und in der globalen Variablen fapi gespeichert. Ihr Konstruktor erwartet die allowed-Flags, sowie optional ein target (Dazu mehr bei der Methode setTarget). Die standard-allowed-Flags, die beim laden der Seite übergeben werden, erlauben das Senden des onmousedown (Ohne Koordinaten), sowie der Content-Höhe. Sie können diese standard-allowed-Flags auch ändern, indem Sie der globalen Variablen fapiStandard am Anfang des Scriptes einen anderen Wert zuweisen.
Eigenschaften von FrameAPI:| target | Speichert das Target (Instanz von FrameCommunicator) die im Konstruktor oder in setTarget übergeben wird. |
| allowed | Speichert die Allowed-Flags, die im Konstruktor oder in setAllowed übergeben werden. |
| evListeners |
Speichert die EventListener, die FrameAPI gesetzt hat.
|
| lastURL | Speichert die letzte gesendete URL, sodass nicht zwei mal die gleiche URL gesendet wird. |
| autoFrameSize | true, nachdem enableAutoFrameSize aufgerufen wurde. Die Frame-Seite wird nun keine Höhen- und Breiteninformationen mehr senden. |
| mouseevent |
Listener-Funktion für Mausevents (Sendet Mausevents).
|
| postState | Sendet Allowed-Flags. |
| resize |
Listener-Funktion für Resize-Events (Sendet Resize-Events).
|
| sendURL | Sendet aktuelle URL. |
| sendTitle | Sendet aktuellen Titel. |
| enableAutoFrameSize | Die Größe mancher Frame-Seiten richtet sich nach der Frame-Größe (z.B. wenn in der Frame-Seite nur ein DIV mit width:100% und height:100% ist). Bei solchen Seiten erzielt die automatische Regelung der Frame-Größ nicht das gewünschte Ergebnis. Daher haben solche Seiten die Möglichkeit, die automatische Regelung durch Aufruf von enableAutoFrameSize zu deaktivieren. (Zugegebener Maßen ist hier meine Begriffswahl ungünstig: Mit enableAutoFrameSize ist gemeint, dass die Höhe nun (automatisch) duch CSS und nicht mehr explizit durch ECMAScript gesteuert wird) Durch den Aufruf von enableAutoFrameSize wird einmalig ein resize mit (-1, -1) ausgelöst, FrameCommunicator setzt dadurch die Größe des Frames auf (autoHeightValue,autoWidthValue) und danach werden keine weiteren resize-Informationen mehr von der Seite gesendet. Bis zum laden einer anderen Seite wird nun die Framegröße durch die in autoWidthValue/autoHeightValue angegebenen CSS-Eigenschaften bestimmt. |
| setTarget |
Setzt ein neues Target. Ein Target ist eine Instanz von FrameCommunicator. Kommen parent- und Frame-Seite von der gleichen Domain, so ist es nicht notwendig, postMessage
zu benutzen, sondern man kann direkt die Methoden der FrameCommunicator-Instanz ansprechen.
|
| setAllowed |
Stellt ein ein, welche allowed-Flags gesetzt werden sollen. Es werden automatisch alle notwendigen EventListener für die gesetzten allowed-Flags erstellt, und nicht
mehr benötigte EventListener gelöscht.
|