Developer Support
Deep Linking for iframe Page Components
3 min read
·
Last updated on Feb 14, 2023
A Page component supports deep linking for its internal pages. There are two supported forms of deep linking you can use: server-side rendering and AJAX rendering. You can also combine the two methods.
Important:
The section-url parameter referenced in this document refers to the Page iframe URL.
AJAX rendering
For AJAX apps, deep linking enables your app to update the content of your iframe without refreshing the whole iframe.Your Page component changes its state using JavaScript and AJAX methods. After the Page component changes its state, it notifies the host website using the Wix.pushState() JavaScript method.
This call will not reload your iframe. Wix will update the top window App-state part of the page URL, allowing it to be shared or copied and pasted to other locations.
Example:
If the browser is showing this URL: http://site.domain.com/page-title/App-state-1
when you call the method: pushState(“App-state-2”) the browser URL will change to http://site.domain.com/page-title/App-state-2 but your Page iframe won't reload.
When a user shares or copies and pastes a link, and there’s a resultant request to render a page with a deep-linked URL state of your Page component, Wix will call your Page with the internal state as part of the iframe’s URL in the App-state path variable. You should load your Page component at the intended internal page state.
Example:
If the browser is showing this URL: http://site.domain.com/page-title/App-state-1
when you call the method: pushState(“App-state-2”) the browser URL will change to http://site.domain.com/page-title/App-state-2 but your Page iframe won't reload.
When a user shares or copies and pastes a link, and there’s a resultant request to render a page with a deep-linked URL state of your Page component, Wix will call your Page with the internal state as part of the iframe’s URL in the App-state path variable. You should load your Page component at the intended internal page state.
Example:
When a user clicks on a link with a URL such as: http://site.domain.com/page-title/App-state Wix will reload the Page iframe using the URL: http://your-section-endpoint-url/App-state?rest-of-the-parameters
Server-side rendering
Deep linking for server-side apps enables your Page component to render different pages depending on the App-state path of your iframe.
A Page component supports deep linking using this flow:
A Page component supports deep linking using this flow:
- Render links in your Page component using the section-url and target parameters (both parameters are passed to your app as part of the Page iframe URL). section-url should be the base URL for your internal pages, and the target parameter should be used as the target attribute of anchor tags.
- When viewing a Page component on a published website, Wix will pass the section-url as the URL of the Page component website page, and the target as _top.
- When a user clicks on such a link, the top window URL changes to the new URL. Full-page reload will not occur. The new URL can be shared or copied and pasted to other locations.
- Wix will catch the history-changed event and will update the Page iframe URL, setting the App-state path parameter to the value “Appended by the App” to the section-url parameter.
- When a user shares or copies and pastes a link, and there’s a resultant request to render a page with a deep-linked URL state of your Page component, Wix will call your Page with the internal state as part of the iframe’s URL in the App-state path variable. You should load your Page component at the intended internal page state.
Example
Assume that there's a Wix website with the domain www.domain.com, which has a Page component on the page www.domain.com/page-title. Also assume that the Page endpoint is www.App.com.
- The following URL will open the Page iframe:
The section-url parameter will be URL encoded. (This example is not encoded for readability.)
1www.App.com/?instance=XXX§ion-url=www.domain.com/page-title/&target=_top&....
- When you render a link to an internal page, such as my-internal-page, you should render:
1<a href="http://www.domain.com/page-title/my-internal-page" target="_top">...</a>
- When a user clicks on this link, the browser top window URL changes:
1http://www.domain.com/App/my-internal-page
- Wix catches the change in the top browser window URL and updates the Page iframe URL:
1www.App.com/my-internal-page?instance=XXX§ion-url=www.domain.com/page-title/&target=_top&...
Note:
Using this flow, your Page component will reload in the iframe with the new URL.
Was this article helpful?
