Thursday, April 30, 2026

SharePoint Classic Blank-Fallback Redirect Page via CEWP

SharePoint Classic — Blank-Fallback Redirect Page via CEWP

Query Parameter Routing · jQuery · Content Editor Web Part · Site Assets · window.top

What This Does and Why You Need It
How It Works — Logic Flow
The Redirect Map
Behaviour Reference
Full Script
Deployment Steps
Technical Notes
Cheat Sheet — Quick Reference

1. What This Does and Why You Need It

The problem

In SharePoint classic, there is no built-in way to route a user to different pages based on a URL parameter. If you are linking to SharePoint from an external system — a PLM tool, a Power Automate notification, an email — and you want one stable URL that fans out to different destinations depending on a short code, you need to build it yourself.

This script gives you exactly that:

A single SharePoint page (/SitePages/Redirect.aspx)
A ?q= query parameter that maps to any destination URL
Instant redirect when a valid key is found
A completely blank white screen when no key matches — no error, no broken layout, nothing

Why client-side?

SharePoint Online does not give you access to web.config or IIS redirect rules. Without a custom SPFx solution or an Azure Function in front, a lightweight jQuery script loaded via the Content Editor Web Part is the most practical approach.

2. How It Works — Logic Flow

Page loads
     ↓
Read window.top.location.search → extract ?q= parameter
     ↓
Look up value in redirectMap object
     ↓
Match found?
  YES → window.top.location.replace(url)   ← instant redirect, no history entry
  NO  → $(document).ready → hide all body children → white background

The key detail: the redirect fires before the DOM renders. When a valid ?q= value is present, the user never sees the SharePoint page at all — they land directly on the destination.

When no match is found, the script waits for $(document).ready and then hides every child element on the parent page, leaving a clean white screen.

3. The Redirect Map

The redirect map is a plain JavaScript object. Keys are short identifiers (numbers, codes, slugs). Values are full absolute URLs.

var redirectMap = {
    "1": "https://[tenant].sharepoint.com/SitePages/Page1.aspx",
    "2": "https://[tenant].sharepoint.com/SitePages/Page2.aspx"
};

To add a new destination, add a new key-value pair:

"3": "https://[tenant].sharepoint.com/SitePages/NewTarget.aspx"

Keys can be any string — numbers work well for short external references. Values must be full absolute URLs.

4. Behaviour Reference

URL	Result
`/SitePages/Redirect.aspx?q=1`	Redirects to destination 1
`/SitePages/Redirect.aspx?q=2`	Redirects to destination 2
`/SitePages/Redirect.aspx`	Blank white page
`/SitePages/Redirect.aspx?q=99`	Blank white page (no match)

5. Full Script

Save this as an .html file (e.g. redirect-handler.html). Upload it to your Site Assets library. Point the Content Editor Web Part's ContentLink property to its URL.

<!DOCTYPE html>
<html>
<head>
    <style>
        body { margin: 0; padding: 0; background-color: #fff; }
    </style>
</head>
<body>

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script type="text/javascript">

    // Redirect map — add or change entries here as needed
    var redirectMap = {
        "1": "https://[TENANT].sharepoint.com/SitePages/Page1.aspx",
        "2": "https://[TENANT].sharepoint.com/SitePages/Page2.aspx"
    };

    // Read ?q= from URL immediately (before DOM renders)
    // window.top used because this script runs inside a CEWP iframe
    var params = new URLSearchParams(window.top.location.search);
    var qValue = params.get("q");

    if (qValue && redirectMap[qValue]) {
        // Redirect instantly — page content never renders
        // replace() avoids adding the redirect page to browser history
        window.top.location.replace(redirectMap[qValue]);

    } else {
        // No match — hide all SharePoint content, show blank white page
        $(document).ready(function () {
            $(window.top.document).find("body").children().hide();
            $(window.top.document.body).css({
                "margin": "0",
                "padding": "0",
                "background-color": "#ffffff",
                "overflow": "hidden"
            });
        });
    }

</script>
</body>
</html>

6. Deployment Steps

Replace [TENANT] placeholders in the redirect map with your actual SharePoint site URLs.
Save the file as redirect-handler.html (or any name you prefer).
Upload the file to your Site Assets library.
Copy the full URL of the uploaded file (e.g. https://[tenant].sharepoint.com/SiteAssets/redirect-handler.html).
Open the SharePoint classic page (Redirect.aspx) in edit mode.
Add a Content Editor Web Part to the page.
Open the Web Part tool pane → set the ContentLink property to the file URL from step 4.
Save and publish the page.
Test with ?q=1, ?q=2, and with no parameter.

Tip: To add more redirect destinations later, just edit the HTML file in Site Assets. No changes to the SharePoint page or Web Part are needed.

7. Technical Notes

Why window.top?

The Content Editor Web Part loads your HTML file inside a hidden <iframe>. The SharePoint chrome — suite bar, page title, content zones — lives on the parent frame. Without window.top, the script can only see the tiny iframe it's running in, not the actual page. All DOM manipulation and URL reads must go through window.top.

Why location.replace() instead of .href?

window.top.location.replace(url) replaces the current history entry rather than pushing a new one. If the user hits the browser back button after being redirected, they will not loop back through the redirect page — they will land on the page they were at before.

Why host the file in Site Assets?

SharePoint Online blocks inline <script> tags inside CEWP rich text fields. The only way to run JavaScript through a CEWP is to upload an external HTML file and reference it via the ContentLink property. Site Assets is the conventional library for these files — it is accessible to all site members by default.

Cross-origin requirement

window.top access requires the CEWP iframe and the parent page to share the same origin. Since both the HTML file (Site Assets) and the SharePoint page are on the same tenant, this is never a problem in practice. It would break if the file were hosted on a different domain.

Browser history note

The redirect uses location.replace(), so the redirect page itself does not appear in the browser's back-navigation history. Destination pages behave normally.

Warning: This approach uses DOM manipulation via window.top, which depends on the CEWP iframe pattern specific to SharePoint classic pages. It will not work on modern SharePoint pages, which do not support the Content Editor Web Part.

8. Cheat Sheet — Quick Reference

File locations

Item	Location
Script file	`/SiteAssets/redirect-handler.html`
SharePoint page	`/SitePages/Redirect.aspx`
Web Part type	Content Editor Web Part (CEWP)
Web Part zone	LeftColumn
jQuery version	3.7.1 (CDN)

Key concepts

CEWP (Content Editor Web Part)
→ Classic SharePoint web part
→ Loads external HTML via ContentLink property
→ Creates a hidden iframe — script runs inside it

window.top
→ Reference to the parent (SharePoint) frame from inside the CEWP iframe
→ Required for all URL reads and DOM manipulation

location.replace(url)
→ Redirect without adding to browser history
→ Use instead of location.href for redirect pages

redirectMap
→ Plain JS object: { "key": "destination-url" }
→ Add entries here when new destinations are needed
→ No other changes required

Troubleshooting

Symptom	Likely cause	Fix
Page loads normally, no redirect	Script file not loading	Check ContentLink URL is correct and file exists in Site Assets
Redirect works but page briefly flashes	DOM renders before script runs	Expected — redirect fires before DOM in all modern browsers; flash is negligible
Blank page not fully white	CSS from SharePoint theme overriding	Ensure `background-color: #ffffff` and `overflow: hidden` are applied to `window.top.document.body`
Script errors in console	Cross-origin block	Confirm HTML file is on the same SharePoint tenant, not an external domain
Works in Chrome, not Edge/Firefox	Browser security policy difference	Verify same-origin requirement; check browser console for specific error

Top 5 tips

ContentLink, not rich text — always reference the HTML file via the ContentLink property, never paste script into the CEWP rich text editor. SharePoint Online strips inline scripts.
window.top for everything — any reference to the parent page (URL, DOM) must go through window.top. Plain document or window only reaches the CEWP iframe.
location.replace() not .href — prevents the redirect page from appearing in browser history. Users can navigate back cleanly.
Extend via list, not hardcode — if destinations change frequently, consider loading the redirect map from a SharePoint list via REST API instead of hardcoding it in the file.
Classic pages only — this technique relies on the Content Editor Web Part, which is not available on modern SharePoint pages. For modern pages, use a SPFx web part or redirect via Power Automate.

AI/ML, AWS, Azure, DevOps, GCP, M365, Microsoft Power Platform, SharePoint

Thursday, April 30, 2026