Embedding the Lesson Finder

Getting the best results out of the Finder for every device width

The Franscape Finder has been designed to ensure a great user experience whatever the device. Redesigned to prioritise a mobile first layout, the user is guided effortlessly to their class with smooth transitions and minimal scrolling. The Finder will responsively fill the container that it is embedded within.

To facilitate a branded experience for customers, the Franscape Finder can be embedded within a website using an iFrame. This allows a brand to leverage the full power of Franscape from within their site. The host site in this scenario, controls the container that the Finder sits in and therefore, determines the users experience. Below are instructions on how to embed the Finder and guidelines for best practice when it comes to user experience.

How it works

The Finder can be embedded using an iFrame. An iFrame contains web content from an external source on a webpage. Typically, this is embedded on the host page at /finder or similar:

https://www.franscape-client.com/finder

The Franscape iFrame can also receive parameters sent to it from the url of the page that hosts it. Most commonly, 'location' is passed to the Finder as a pre-set for clients to send specific finder results to a customer:

https://www.franscape-client.com/finder?location=Birmingham

For information on more parameters, please see: How to Pre-filter the Lesson Finder?

The Finder intentionally does not include any navigation and supporting content so that it can be embedded in an external host and create a seamless experience as if it was created as part of the host site.

The Basics - how to physically embed the Finder

The specifics about how to add the code to a host site vary depending on the web platform and how much access you have to the physical code. In most cases, an 'embed' option is made available and this is where the Franscape code be pasted.

If you're unsure how to do this;

1. If on a popular 'build-your-own' platform, like Squarespace of Wix, google 'How to embed iFrame on {platform name}'
2. If your site was built for you, send this article to your web company.

The embed code

Copy the following code into the source of your webpage, or the 'embed' feature of your editor.

<section id="franscape-finder">


     <!-- THESE STYLES ENSURE THE FINDER FILLS THE HOST SITE SPACE -->

     <style>
          #franscape-finder,
          #franscape-finder-iframe {
               width: 100%;
               height: 100%;
               margin: 0;
               padding: 0;
               border: 0;
               position: relative;
          }
     </style>


     <!-- THIS IS THE ACTUAL IFRAME -->

     <iframe
          id="franscape-finder-iframe"
          width="100%"
          allow="geolocation"
          name="Lesson Finder"
          title="Client Lesson Finder"></iframe>


     <!-- THIS SCRIPT ALLOWS PARAMETERS FROM THE URL TO BE PASSED TO THE FINDER -->

     <script>
          const iframeEl = document.getElementById('franscape-finder-iframe');
          iframeEl.src = 'https://finder.client.franscape.io/' + window.location.search;
     </script>

</section>

title="Franscape Lesson Finder">

iframeEl.src = 'https://finder.franscape.franscape.io/' + window.location.search;

Getting the best from the Finder

The Franscape Finder is fully responsive and designed to be the main content of the host page. This allows it to occupy as much of the screen as possible making it easier for your customers to browse classes, particularly when at mobile. It is assumed that the host website is also fully responsive and usable at mobile.

It is recommended to exclude everything from the page except for your header and navigation. This includes the Footer and any headings or paragraphs. As tempting as it might be to surround the Finder with additional information, please don't. The finder includes help text so it's not necessary to provide any explanation or supplementary content. Any content from the host site on the page is competing with the usability of the finder itself.

As content within the Finder scrolls within the Finder, if the host page also scrolls this can result in confusing double scrolling. This is unhelpful to the user and in the worst cases can render the page unusable. For this reason it is best to exclude all unnecessary content and ensure that the host page occupies the full viewport without scrolling.

Avoiding the dreaded 'double-scroll'

The basic principle is to ensure there is only one piece of scrolling content on any webpage. As the Finder includes scrolling content, it's important to ensure the host page does not. If you or your web developer have access to the code, the following will give you the best result.

Just the essentials

In an ideal world, your page would only include your header, the Finder and any navigation required to allow users to browse your site (please note, this only applies to the page of your website that hosts the Finder).

The container for the Finder should be at a similar level to your header in the markup, indicated by <header> and <main> in the following code snippet.

<html lang="en">

    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no, viewport-fit=cover" />
        ...
    </head>

    <body>

        <div class="possible-wrapper">

            <header class="main-navigation-and-branding">...</header>

            <main>
                <section> <!-- OPTIONAL - FEEL FREE TO EXCLUDE -->
                    <iframe
                        width="100%"
                        allow="geolocation"
                        name="Lesson Finder"
                        title="Client Lesson Finder"></iframe>
                    <script>
                        const iframeEl = document.getElementById('franscape-finder-iframe');
                        iframeEl.src = 'https://finder.client.franscape.io/' + window.location.search;
                    </script>
                </section>
            </main>

        </div>

        <aside class="mobile-navigation">...</aside>

    </body>

</html>

Viewport - Fluid Scaling

Most websites are already setup for fully responsive layouts. To make sure, a website should fluidly scale from mobile to desktop. To allow this to happen, it requires a 'viewport' declaration in the <head> of the html.

<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no, viewport-fit=cover" />

It's possible to check this on your site by right clicking and selecting 'View source'. If it does not exist in your code, contact your web-provider to speak to them about including it.

Max-width - Let it grow

Often websites will provide a container for content that keeps it from scaling to the full width of the page, leaving margins on mobile and large gaps at desktop. Whilst that's helpful for written content like this article, it's best if the Finder is allowed to grow to the full width of the page without a containing parent div.

If the host website includes containers with margins, padding or max-width, you may need to setup a separate template that does not include such a container, or override the styles of the container with custom styles.

Fix the header

Set your header as a fixed element on the page. This will ensure that it doesn't move as content within the Finder scrolls.

You can do this with the following styles:

.main-navigation-and-branding {
    position: fixed;
    top: 0;
    right: 0;
    left: 0;
    width: 100%;
}

Specify height

The iFrame for the Finder will inherit its height from the host. If height is not declared, it will fallback to an undeclared state, which is often height: 0. This is not helpful. As devices come in all sizes, it's not possible to declare an absolute height as this would be too tall on some devices and too small on others.

Height needs to be relative to the viewport to get the best results. Ideally, the iFrame container would occupy the full height of the viewport minus the space used by the header.

As 100vh produces inconsistent results on mobile as the viewport height changes with scroll position, it is best to use percent. Height as a percent is inherited from the HTML object itself and so needs declaring for every object in the hierarchy. Flex grow, also can't help here, the iFrame needs a height that is actively declared.

Declare height: 100% on your html, body and any other parents in the tree until you get to the Header and Finder.

In the example above, the hierarchy is:

• html (height: 100%)
  • body (height: 100%)
    • .possible-wrapper (height: 100%)
      • header (allow the content to define this height)
      • main (height: 100% minus the height of the header)
        • section (height: 100%)
          • iFrame (height: 100%)

In this example, the only element that does not have a height of 100% is the <main> element. This is because the height is inherited directly from the parent. Therefore, the children of main also have a height of 100%, because it is 100% of the parent, which is <main>.

So we can set those heights with just a small amount of CSS:

html,
body,
.possible-wrapper,
section,
iframe {
    height: 100%;
}

Calculating the height of main

To work out what the height of main is, we can use the 'calc' function of CSS.

main {
    height: calc(100% - {header-height});
}

However, we need to work out what {header-height} is. This is very simple. If you use the browser tools to inspect the header element, it will tell you what its height is.

In this example, the height is 56px.

So our calculation is:

main {
    height: calc(100% - 56px);
}

Unfortunately, we're not finished. In most cases the header is different sizes between mobile, tablet and desktop. So we need to declare the height of <main> for each of these screen widths.

Allowing for different screen widths

Most responsive websites use media-queries to declare different layout rules at different screen widths. These are very helpful declarations in the CSS that allow the developer to define styles for certain 'breakpoints', where a breakpoint is just a point by which the new rules are applied.

The syntax for these declarations is very simple. If our header's height is 56px at the smallest screen widths (mobiles), but at a tablet size our header increases in height to 80px.

We would declare this like so:

main {
    height: calc(100% - 56px);
}

@media screen and (min-width: 768px) {
    main {
        height: calc(100% - 80px);
    }
}

The declaration above, says that when a device has a screen width equal or greater to 768px, that the calculation for the height of 'main' is now 100% - 80px.

This same process can then be repeated for each breakpoint that the height of the header changes.

That little notch on mobile

We also need to account for the space in mobile browsers that is sometimes occupied by the address bar or the notch area. A space that changes depending on scroll position. You may have noticed that on iOS, the space at the bottom of the browser changes height based on your scroll position (this is why we're using percent instead of viewport height).

Helpfully, browsers make is easy for us to calculate that space with an object called env(safe-area-inset-top) and env(safe-area-inset-bottom).

To include this in the CSS, it now looks like this:

main {
    height: calc(100% - 56px - env(safe-area-inset-top) - env(safe-area-inset-bottom));
}

@media screen and (min-width: 768px) {
    main {
        height: calc(100% - 80px - env(safe-area-inset-top) - env(safe-area-inset-bottom));
    }
}

@media screen and (min-width: 1200px) {
    main {
        height: calc(100% - 100px - env(safe-area-inset-top) - env(safe-area-inset-bottom));
    }
}

And test...

Once you've completed each of the steps above, everything should work well. We recommend testing things carefully, especially on mobile. Scroll through the app and check that everything is usable.