# Editing Pages with iFrames

## Inline Frames

An iframe (inline frame) is used to embed a document inside the current document. The embedded document can be from the same site, or a different site.

Framed documents are separate/distinct from the top-level tab. A separate “instance” of PixieBrix runs in each iframe.

The Page Editor works on the top-level frame of the tab. It cannot directly select/modify elements in the document embedded within an iframe.

In selection/placement mode, when part of the page is an iframe, PixieBrix will highlight the whole iframe on hover because to the Page Editor, the iframe is a single element:

<figure><img src="/files/Kl15pDMSDfHBwKmsG4og" alt=""><figcaption><p>The Page Editor element selector over an iframe: <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe</a></p></figcaption></figure>

## Editing a Framed Page

IFrames are distinct documents. To edit a document in an iframe with PixieBrix, you’ll edit the document and not the containing tab.

To extend a framed document with PixieBrix, you have two options:

1. Preferred: Open the framed document in its own tab and use the Page Editor
2. Use the Page Editor on the top-level tab, and manually write element selectors

### Find the URL of the iframe

1. Use the Chrome Dev Tools element selector

   ![](/files/PYpFGGyMthO0Eb52qBkK)
2. Select an element within the frame
3. Find the iframe ancestor element. It will have tag `<iframe>` and show a `#document` sub node:

   <figure><img src="/files/qJBo9Ba2BkStWSbqvBWz" alt=""><figcaption></figcaption></figure>
4. Right click the `src` attribute value and click “Copy link address”. This will copy a link address to the clipboard (including the origin if the `src` attribute does not already include it)

   <figure><img src="/files/Nf2yLofEbq1sZqiZGspW" alt=""><figcaption></figcaption></figure>

### Opening the Framed Document in its Own Tab

{% hint style="info" %}
Not all framed pages can be opened in their own tab. Some documents are configured to re-direct if they detect they’re not running inside a frame
{% endhint %}

1. Find the URL of the iframe (see above)
2. Open a new tab and navigate to the document URL
3. Open the Page Editor and edit the page as usual

### Editing from the Top-Level Tab

{% hint style="info" %}
The Page Editor dynamically updates mods on the top-level tab. To run an updated mod in the iframed documents, you must Save the mod.
{% endhint %}

1. Find the URL of the iframe (see above)
2. Add the mod in the Page Editor
3. Modify the “Sites” to match the source of the framed document
4. Build the mod as normal, but manually write elements selectors. (Because the Page Editor cannot select elements in iframes)
5. Save the Mod
6. Right-click on the frame and select “Reload Frame” from the Chrome context menu:

   <figure><img src="/files/jVmlnHyQkvdhFfS8iQea" alt=""><figcaption></figcaption></figure>
7. Your Mod will run inside the framed document

## Cross-frame Communication

### Running a Brick in the Top-Level Frame on a Tab

To run a brick in the top-level frame on the page, set the Advanced Options > Target Tab/Frame to “Top-level Frame”

<figure><img src="/files/YV7ArSDLefNe1r2dkC7l" alt="" width="375"><figcaption><p>Configuring a brick to run in the top-level frame</p></figcaption></figure>

### Transferring Data from an Inline Frame to the Top-Level Frame

#### Approach 1: Assigning a Mod Variable in the Top-Level Frame

To make data from an inline frame available to the Top-Level Frame, use the `Assign Mod Variable` brick in conjunction with the Target Tab/Frame option.

When the brick runs, it will set the mod variable of the Top-Level Frame.

<figure><img src="/files/2BPyFPM2kG9l70YpAEKr" alt="" width="375"><figcaption><p>Sending data from an inner frame to the top-level frame</p></figcaption></figure>

#### Approach 2: Running a brick in All Frames

To run a brick in all frames on the page, set the Advanced Options > Target Tab/Frame to “All Frames”. The brick will return an array of values (a value per frame)

<figure><img src="/files/6B1REsbZN7XNgTtuc3pF" alt="" width="375"><figcaption><p>Configuring a brick to run in All Frames</p></figcaption></figure>

### Transferring Data from the Top-Level Frame to an Inline Frame

#### Approach 1: Push data from the Top-Level Frame to All Frames

To push data from a Top-Level Frame to frames on the page. Use the `Assign Mod Variable` brick and set the Advanced Options > Target Tab/Frame to “All Frames”.

<figure><img src="/files/TvleOASV3oIOD2JBddzK" alt="" width="375"><figcaption><p>Assigning a Mod Variable in All Frames</p></figcaption></figure>

#### Approach 2: Read/Poll data from the Top-Level Frame

To retrieve information from the Top-Level Frame, set Advanced Options > Target Tab/Frame for the brick to "Top-Level Frame":

<figure><img src="/files/kr9YpZTMMRuI7V8mo5Ma" alt="" width="375"><figcaption><p>Configuring a brick to run in the Top-Level Frame</p></figcaption></figure>

To read the Mod Variables from the Top-Level Frame, use the `Get shared page state` brick:

<figure><img src="/files/kMMh6LTeqaHTYLoLlCkb" alt="" width="375"><figcaption><p>Reading Mod Variables from the Top-Level Frame</p></figcaption></figure>

**Determining When to Read/Poll Information from the Top-Level Frame**

An Inline Frame may load prior to the Top-Level Frame being ready. Therefore, you must take extra steps to ensure that the data is available reliably.

Some common approaches are:

* If the data is loaded on page load: Use the "Wait for a DOM element” brick with Target Tab/Frame: Top-level Frame to wait for the information to be available
* If the data may change: Use an Interval Trigger as the Starter Brick to poll for data
* Use Wait/Sleep to provide an opportunity for the Top-Level Frame to load

### Sending Messages to Frames to Trigger Native Javascript Handlers with the “**Post Message to a Frame” brick**

{% hint style="info" %}
This use case is advanced/special. You generally will not use the “Post Message to a Frame” brick unless you are instructed to by the host application’s documentation
{% endhint %}

Some Javascript applications listen for events from other frames to support events and data transfer. These applications use the Javascript [Window postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)

To send a message to a frame on the page, use the “Post Message to a Frame” brick. The brick has the following options:

* selector: the iframe to message
* message: the message payload. The shape will depend on what the receiver/listener expects to receive
* targetOrigin: the origin (schema, hostname, port) of the intended recipient, or `*` not to validate the target frame’s origin. Used to prevent sending sensitive information to the wrong location

<figure><img src="/files/X5K5B8wMACbq6Ujp8sxt" alt="" width="375"><figcaption><p>Example configuration of the “Post message to a frame” brick</p></figcaption></figure>

### Working with Salesforce CK Editor&#x20;

**Extracting Text from the CK Editor**

To extract text from the CK Editor, you'll need to use the **Run Bricks** brick (target in All Frames), with the Traverse Elements brick targeting `body[contenteditable="true"]`. Then add the **HTML Reader** brick  to reference the output element. Here's an example: <br>

<figure><img src="/files/j4Fs7VEtcWiJtdkk75EF" alt=""><figcaption></figcaption></figure>

**Inserting Text into the CK Editor**

To insert text, you can use the same **Run Bricks** brick in All Frames, and inside use the Insert HTML Element targeting the `body[contenteditable="true"]` selector to prepend the element.&#x20;

<figure><img src="/files/qoJs7cjIkpYJBmZIL0s2" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pixiebrix.com/how-to/editing-pages-with-iframes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.