annotate iframe-resizer/README.md @ 2:e8755431a0cd draft

fixed missing dependencies
author saskia-hiltemann
date Tue, 30 Sep 2014 09:47:14 -0400
parents ac5f9272033b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
1 # iFrame Resizer
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
2 [![Bower version](https://badge.fury.io/bo/iframe-resizer.png)](http://badge.fury.io/bo/iframe-resizer) [![Build Status](https://travis-ci.org/davidjbradshaw/iframe-resizer.png?branch=master)](https://travis-ci.org/davidjbradshaw/iframe-resizer) [![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
3
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
4 This library enables the automatic resizing of the height and width of both same and cross domain iFrames to fit the contained content. It uses [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/window.postMessage) to pass messages between the host page and the iFrame and when available [MutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver) to detect DOM changes, with a fallback to setInterval for IE8-10.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
5
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
6 The code also detects browser events that can cause the content to resize; provides functions to allow the iFrame to set a custom size and close itself. Plus it supports having multiple iFrames on the host-page and additionally provides for the sending of simple messages from the iFrame to the parent page.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
7
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
8 For security, by default the host-page automatically checks that the origin of incoming messages are from the domain of the page listed in the `src` property of the iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
9
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
10 The package contains two minified JavaScript files in the [js](js) folder. The first ([iframeResizer.min.js](https://raw2.github.com/davidjbradshaw/iframe-resizer/master/js/iframeResizer.min.js)) is for the page hosting the iFrames. It can be called with **native** JavaScript;
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
11
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
12 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
13 iFrameResize([{options}],[selector]);
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
14 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
15
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
16 or via **jQuery**. (See [notes](#browser-compatibility) below for using native version with IE8).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
17
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
18 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
19 $('iframe').iFrameResize([{options}]);
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
20 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
21
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
22 The second file ([iframeResizer.contentWindow.min.js](https://raw.github.com/davidjbradshaw/iframe-resizer/master/js/iframeResizer.contentWindow.min.js)) is a **native** JavaScript file that needs placing in the page contained within your iFrame. <i>This file is designed to be a guest on someone else's system, so has no dependancies and won't do anything until it's activated by a message from the containing page</i>.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
23
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
24 ### Typical setup
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
25
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
26 The normal configuration is to have the iFrame resize when the browser window changes size or the content of the iFrame changes. To set this up you need to configure one of the dimensions of the iFrame to a percentage and tell the library only to update the other dimension. Normally you would set the width to 100% and have the height scale to fit the content.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
27
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
28 ```html
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
29 <iframe src="http://anotherdomain.com/frame.content.html" width="100%" scrolling="no"></iframe>
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
30 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
31
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
32 Note that scrolling is set to 'no', as older versions of IE don't allow this to be turned off in code and can just slightly add a bit of extra space to the bottom of the content that it doesn't report when it returns the height. If you have problems, check the [troubleshooting](#troubleshooting) section below.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
33
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
34 ###Example
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
35 To see this working take a look at this [example](http://davidjbradshaw.com/iframe-resizer/example/) and watch the [console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
36
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
37 ## Options
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
38
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
39 ### log
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
40
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
41 default: false
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
42 type: boolean
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
43
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
44 Setting the `log` option to true will make the scripts in both the host page and the iFrame output everything they do to the JavaScript console so you can see the communication between the two scripts.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
45
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
46 ### autoResize
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
47
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
48 default: true
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
49 type: boolean
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
50
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
51 When enabled changes to the Window size or the DOM will cause the iFrame to resize to the new content size. Disable if using size method with custom dimensions.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
52
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
53 ### bodyBackground
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
54
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
55 default: null
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
56 type: string
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
57
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
58 Override the body background style in the iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
59
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
60 ### bodyMargin
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
61
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
62 default: null
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
63 type: string || number
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
64
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
65 Override the default body margin style in the iFrame. A string can be any valid value for the CSS margin attribute, for example '8px 3em'. A number value is converted into px.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
66
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
67 ### checkOrigin
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
68
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
69 default: true
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
70 type: boolean
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
71
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
72 When set to true, only allow incoming messages from the domain listed in the `src` property of the iFrame tag. If your iFrame navigates between different domains, ports or protocols; then you will need to disable this option.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
73
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
74 ### enablePublicMethods
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
75
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
76 default: false
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
77 type: boolean
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
78
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
79 If enabled, a `window.parentIFrame` object is created in the iFrame that contains methods outlined [below](#iframe-methods).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
80
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
81 ### interval
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
82
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
83 default: 32 (in ms)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
84 type: number
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
85
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
86 In browsers that don't support [mutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver), such as IE10, the library falls back to using setInterval, to check for changes to the page size. The default value is equal to two frame refreshes at 60Hz, setting this to a higher value will make screen redraws noticeable to the user.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
87
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
88 Setting this property to a negative number will force the interval check to run instead of [mutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
89
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
90 Set to zero to disable.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
91
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
92 ### heightCalculationMethod
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
93
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
94 default: 'bodyOffset'
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
95 values: 'bodyOffset' | 'bodyScroll' | 'documentElementOffset' | 'documentElementScroll' |
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
96 'max' | 'min' | 'grow' | 'lowestElement'
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
97
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
98 By default the height of the iFrame is calculated by converting the margin of the `body` to <i>px</i> and then adding the top and bottom figures to the offsetHeight of the `body` tag.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
99
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
100 In cases where CSS styles causes the content to flow outside the `body` you may need to change this setting to one of the following options. Each can give different values depending on how CSS is used in the page and each has varying side-effects. You will need to experiment to see which is best for any particular circumstance.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
101
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
102 * **bodyScroll** uses `document.body.scrollHeight`
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
103 * **documentElementOffset** uses `document.documentElement.offsetHeight`
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
104 * **documentElementScroll** uses `document.documentElement.scrollHeight`
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
105 * **max** takes the largest value of the main four options
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
106 * **min** takes the smallest value of the main four options
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
107 * **grow** same as **max** but disables the double resize that is used to workout if the iFrame needs to shrink. This provides much better performance if your iFrame will only ever increase in size
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
108 * **lowestElement** Loops though every element in the the DOM and finds the lowest bottom point.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
109
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
110 <i>Notes:</i>
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
111
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
112 <i>The **bodyScroll**, **documentElementScroll**, **max** and **min** options can cause screen flicker and will prevent the [interval](#interval) trigger downsizing the iFrame when the content shrinks. This is mainly an issue in IE 10 and below, where the [mutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver) event is not supported. To overcome this you need to manually trigger a page resize by calling the [parentIFrame.size()](#size-customheight-customwidth) method when you remove content from the page.</i>
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
113
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
114 <i>The **lowestElement** option is the most reliable way of determining the page height. However, it does have a performance impact in older versions of IE. In one screen refresh (16ms) Chrome 34 can calculate the position of around 10,000 html nodes, whereas IE 8 can calculate approximately 50. It is recommend to fallback to **max** or **grow** in IE10 and below.</i>
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
115
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
116 ### maxHeight / maxWidth
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
117
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
118 default: infinity
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
119 type: integer
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
120
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
121 Set maximum height/width of iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
122
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
123 ### minHeight / minWidth
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
124
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
125 default: 0
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
126 type: integer
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
127
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
128 Set minimum height/width of iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
129
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
130 ### scrolling
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
131
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
132 default: false
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
133 type: integer
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
134
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
135 Enable scroll bars in iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
136
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
137 ### sizeHeight
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
138
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
139 default: true
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
140 type: boolean
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
141
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
142 Resize iFrame to content height.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
143
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
144 ### sizeWidth
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
145
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
146 default: false
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
147 type: boolean
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
148
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
149 Resize iFrame to content width.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
150
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
151 <!--
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
152 ### tolerance
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
153
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
154 default: 0
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
155 type: integer
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
156
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
157 Set amount iFrame content size has to change by, before triggering resize of the iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
158 -->
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
159
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
160 ## Callback Methods
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
161
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
162 ### closedCallback
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
163
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
164 type: function (iframeID)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
165
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
166 Called when iFrame is closed via `parentIFrame.close()` method.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
167
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
168 ### initCallback
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
169
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
170 type: function (iframe)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
171
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
172 Initial setup callback function.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
173
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
174 ### messageCallback
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
175
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
176 type: function ({iframe,message})
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
177
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
178 Receive message posted from iFrame with the `parentIFrame.sendMessage()` method.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
179
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
180 ### resizedCallback
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
181
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
182 type: function ({iframe,height,width,type})
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
183
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
184 Function called after iFrame resized. Passes in messageData object containing the **iFrame**, **height**, **width** and the **type** of event that triggered the iFrame to resize.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
185
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
186
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
187 ## IFrame Methods
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
188
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
189 To enable these methods you must set [enablePublicMethods](#enablepublicmethods) to **true**. This creates the `window.parentIFrame` object in the iFrame. These method should be contained by a test for the `window.parentIFrame` object, in case the page is not loaded inside an iFrame. For example:
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
190
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
191 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
192 if ('parentIFrame' in window) {
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
193 parentIFrame.close();
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
194 }
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
195 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
196
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
197 ### close()
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
198
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
199 Remove the iFrame from the parent page.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
200
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
201 ### getId()
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
202
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
203 Returns the ID of the iFrame that the page is contained in.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
204
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
205 ### sendMessage(message,[targetOrigin])
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
206
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
207 Send string to the containing page. The message is delivered to the `messageCallback` function. The `targetOrigin` option is used to restrict where the message is sent to; to stop an attacker mimicking your parent page. See the MDN documentation on [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window.postMessage) for more details.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
208
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
209 ### setHeightCalculationMethod(heightCalculationMethod)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
210
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
211 Change the method use to workout the height of the iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
212
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
213 ### size ([customHeight],[ customWidth])
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
214
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
215 Manually force iFrame to resize. This method optionally accepts two arguments: **customHeight** & **customWidth**. To use them you need first to disable the `autoResize` option to prevent auto resizing and enable the `sizeWidth` option if you wish to set the width.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
216
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
217 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
218 iFrameResize({
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
219 autoResize: false,
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
220 enablePublicMethods: true,
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
221 sizeWidth: true
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
222 });
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
223 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
224
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
225 Then you can call the `size` method with dimensions:
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
226
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
227 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
228 if ('parentIFrame' in window) {
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
229 parentIFrame.size(100); // Set height to 100px
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
230 }
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
231 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
232
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
233
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
234 ##Troubleshooting
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
235
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
236 The first step to investigate a problem is to enable the [log](#log) option and then open the [JavaScript Console](https://developers.google.com/chrome-developer-tools/docs/console#opening_the_console). This will enable you to see what both the iFrame and host page are up to and also see any JavaScript error messages.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
237
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
238 Solutions for the most common problems are outlined in this section.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
239
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
240 ### IFrame not sizing correctly
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
241 If a larger element of content is removed from the normal document flow, through the use of absolute positioning, it can prevent the browser working out the correct size of the page. In such cases you can change the [heightCalculationMethod](#heightcalculationmethod) to uses one of the other sizing methods, normally you will be best off selecting the **max** or **lowestElement** options to avoid cross browser differences.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
242
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
243 ###IFrame not detecting CSS :hover events
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
244 If your page resizes via CSS `:hover` events, these won't be detect by default. It is however possible to create `mouseover` and `mouseout` event listeners on the elements that are resized via CSS and have these events call the [parentIFrame.size()](##parentiframesize-customheight-customwidth) method. With jQuery this can be done as follows, once you have set the [enablePublicMethods](#enablepublicmethods) option to **true**.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
245
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
246 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
247 function resize(){
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
248 if ('parentIFrame' in window) {
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
249 setTimeout(function(){ // Fix FireFox timing issue
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
250 parentIFrame.size();
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
251 },0);
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
252 }
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
253 }
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
254
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
255 $(*Element with hover style*).hover(resize);
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
256 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
257
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
258 ### PDF and OpenDocument Files
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
259 It is not possible to add the required JavaScript to PDF and ODF files. However, you can get around this limitation by using [ViewerJS](http://viewerjs.org/) to render these files inside a HTML page, that also contains the iFrame JavaScript file ([iframeResizer.contentWindow.min.js](https://raw.github.com/davidjbradshaw/iframe-resizer/master/js/iframeResizer.contentWindow.min.js)).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
260
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
261 ### Unexpected message received error
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
262 By default the origin of incoming messages is checked against the `src` attribute of the iFrame. If they don't match an error is thrown. This behaviour can be disabled by setting the [checkOrigin](#checkorigin) option to **false**.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
263
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
264
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
265 ## Browser compatibility
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
266 ###jQuery version
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
267
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
268 Works with all browsers which support [window.postMessage](http://caniuse.com/#feat=x-doc-messaging) (IE8+).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
269
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
270 ###Native version
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
271
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
272 Additionally requires support for [Array.prototype.forEach](http://kangax.github.io/es5-compat-table/#Array.prototype.forEach) (IE9+) and [document.querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document.querySelectorAll) (IE8 Standards Mode). For **IE8** force [Standards Mode](http://en.wikipedia.org/wiki/Internet_Explorer_8#Standards_mode),
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
273
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
274 ```html
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
275 <meta http-equiv="X-UA-Compatible" content="IE=edge">
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
276 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
277
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
278 and use the [MDN PolyFill](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on the host page.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
279
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
280 ```js
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
281 if (!Array.prototype.forEach){
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
282 Array.prototype.forEach = function(fun /*, thisArg */){
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
283 "use strict";
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
284 if (this === void 0 || this === null || typeof fun !== "function") throw new TypeError();
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
285
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
286 var
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
287 t = Object(this),
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
288 len = t.length >>> 0,
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
289 thisArg = arguments.length >= 2 ? arguments[1] : void 0;
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
290
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
291 for (var i = 0; i < len; i++)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
292 if (i in t)
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
293 fun.call(thisArg, t[i], i, t);
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
294 };
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
295 }
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
296 ```
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
297
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
298
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
299 ## Contributing
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
300 In lieu of a formal style-guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt](http://gruntjs.com/).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
301
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
302
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
303 ##Version History
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
304
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
305 * v2.5.0 Added *minHeight*, *maxHeight*, *minWidth* and *maxWidth* options. Added *initCallback* and *closedCallback* functions (Close event calling *resizedCallback* is deprecated). Added **grow** and **lowestElement** *heightCalculationMethods*. Added AMD support. [#52](https://github.com/davidjbradshaw/iframe-resizer/issues/52) Added *sendMessage* example. [#54](https://github.com/davidjbradshaw/iframe-resizer/issues/54) Work around IE8's borked JS execution stack. [#55](https://github.com/davidjbradshaw/iframe-resizer/issues/55) Check datatype of passed in options.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
306 * v2.4.8 Fix issue when message passed to messageCallback contains a colon.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
307 * v2.4.7 [#49](https://github.com/davidjbradshaw/iframe-resizer/issues/49) Deconflict requestAnimationFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
308 * v2.4.6 [#46](https://github.com/davidjbradshaw/iframe-resizer/issues/46) Fix iFrame event listener in IE8.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
309 * v2.4.5 [#41](https://github.com/davidjbradshaw/iframe-resizer/issues/41) Prevent error in FireFox when body is hidden by CSS [[Scott Otis](/Scotis)].
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
310 * v2.4.4 Enable nested iFrames ([#31](https://github.com/davidjbradshaw/iframe-resizer/issues/31) Filter incoming iFrame message in host-page script. [#33](https://github.com/davidjbradshaw/iframe-resizer/issues/33) Squash unexpected message warning when using nested iFrames. Improved logging for nested iFrames). [#38](https://github.com/davidjbradshaw/iframe-resizer/issues/38) Detect late image loads that cause a resize due to async image loading in WebKit [[Yassin](/ynh)]. Fixed :Hover example in FireFox. Increased trigger timeout lock to 64ms.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
311 * v2.4.3 Simplified handling of double fired events. Fixed test coverage.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
312 * v2.4.2 Fix missing 'px' unit when resetting height.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
313 * v2.4.1 Fix screen flicker issue with scroll height calculation methods in v2.4.0.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
314 * v2.4.0 Improved handling of alternate sizing methods, so that they will now shrink on all trigger events, except *Interval*. Prevent error when incoming message to iFrame is an object.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
315 * v2.3.2 Fix backwards compatibility issue between V2 iFrame and V1 host-page scripts.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
316 * v2.3.1 Added setHeightCalculationMethod() method in iFrame. Added *min* option to the height calculation methods. Invalid value for *heightCalculationMethod* is now a warning rather than an error and now falls back to the default value.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
317 * v2.3.0 Added extra *heightCalculationMethod* options. Inject clearFix into 'body' to work around CSS floats preventing the height being correctly calculated. Added meaningful error message for non-valid values in *heightCalculationMethod*. Stop **click** events firing for 50ms after **size** events. Fixed hover example in old IE.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
318 * v2.2.3 [#26](https://github.com/davidjbradshaw/iframe-resizer/issues/26) Locally scope jQuery to $, so there is no dependancy on it being defined globally.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
319 * v2.2.2 [#25](https://github.com/davidjbradshaw/iframe-resizer/issues/25) Added click listener to Window, to detect CSS checkbox resize events.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
320 * v2.2.1 [#24](https://github.com/davidjbradshaw/iframe-resizer/issues/24) Prevent error when incoming message to host page is an object [[Torjus Eidet](https://github.com/torjue)].
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
321 * v2.2.0 Added targetOrigin option to sendMessage function. Added bodyBackground option. Expanded troubleshooting section.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
322 * v2.1.1 [#16](https://github.com/davidjbradshaw/iframe-resizer/issues/16) Option to change the height calculation method in the iFrame from offsetHeight to scrollHeight. Troubleshooting section added to docs.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
323 * v2.1.0 Added sendMessage() and getId() to window.parentIFrame. Changed width calculation to use scrollWidth. Removed deprecated object name in iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
324 * v2.0.0 Added native JS public function, renamed script filename to reflect that jQuery is now optional. Renamed *do(Heigh/Width)* to *size(Height/Width)*, renamed *contentWindowBodyMargin* to *bodyMargin* and renamed *callback* *resizedCallback*. Improved logging messages. Stop *resize* event firing for 50ms after *interval* event. Added multiple page example. Workout unsized margins inside the iFrame. The *bodyMargin* property now accepts any valid value for a CSS margin. Check message origin is iFrame. Removed deprecated methods.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
325 * v1.4.4 Fixed *bodyMargin* bug.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
326 * v1.4.3 CodeCoverage fixes. Documentation improvements.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
327 * v1.4.2 Fixed size(250) example in IE8.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
328 * v1.4.1 Setting `interval` to a negative number now forces the interval test to run instead of [MutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
329 * v1.4.0 [#12](https://github.com/davidjbradshaw/iframe-resizer/issues/12) Option to enable scrolling in iFrame, off by default. [#13](https://github.com/davidjbradshaw/iframe-resizer/issues/13) Bower dependancies updated.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
330 * v1.3.7 Stop *resize* event firing for 50ms after *size* event. Added size(250) to example.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
331 * v1.3.6 [#11](https://github.com/davidjbradshaw/iframe-resizer/issues/11) Updated jQuery to v1.11.0 in example due to IE11 having issues with jQuery v1.10.1.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
332 * v1.3.5 Documentation improvements. Added Grunt-Bump to build script.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
333 * v1.3.0 IFrame code now uses default values if called with an old version of the host page script. Improved function naming. Old names have been deprecated and removed from docs.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
334 * v1.2.5 Fix publish to [plugins.jquery.com](https://plugins.jquery.com).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
335 * v1.2.0 Added autoResize option, added height/width values to iFrame public size function, set HTML tag height to auto, improved documentation [All [Jure Mav](https://github.com/jmav)]. Plus setInterval now only runs in browsers that don't support [MutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver) and is on by default, sourceMaps added and close() method introduced to parentIFrame object in iFrame.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
336 * v1.1.1 Added event type to messageData object.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
337 * v1.1.0 Added DOM [MutationObserver](https://developer.mozilla.org/en/docs/Web/API/MutationObserver) trigger to better detect content changes in iFrame, [#7](https://github.com/davidjbradshaw/iframe-resizer/issues/7) Set height of iFrame body element to auto to prevent resizing loop, if it's set to a percentage.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
338 * v1.0.3 [#6](https://github.com/davidjbradshaw/iframe-resizer/issues/6) Force incoming messages to string. Migrated to Grunt 4.x. Published to Bower.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
339 * v1.0.2 [#2](https://github.com/davidjbradshaw/iframe-resizer/issues/2) mime-type changed for IE8-10.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
340 * v1.0.0 Initial published release.
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
341
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
342
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
343 ## License
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
344 Copyright &copy; 2013-14 [David J. Bradshaw](https://github.com/davidjbradshaw).
ac5f9272033b first upload
saskia-hiltemann
parents:
diff changeset
345 Licensed under the [MIT license](http://opensource.org/licenses/MIT).