Wayfinder can be embedded into your site if you are using OpenAthens Keystone. Which is kinda cool.

Get the code from the publisher dashboard

  1. Sign in to the publisher dashboard (https://sp.openathens.net

  2. Select the OpenID Connect application in question and go to its discovery tab

  3. Scroll to the  discovery method section and select the radio button for Wayfinder

  4. In the authorised domains add the internet domain(s) where you will be using Wayfinder (e.g. *.yourdomain.com

  5. Go to the Wayfinder tab

  6. Copy the JavaScript 

The code is tied to the specific Keystone application since Wayfinder needs to know where to return the user. If you need to support multiple apps from a common login page you will need to find a way to insert the relevant oaAppId (coloured red in the interface). 

Add the code to your website

  1. Paste the Javascript into the <HEAD> of the page (or site if necessary).

  2. The code can be invoked by two methods:

    1. If you want Wayfinder to appear as an overlay, use the wayfinder-login selector in the trigger - e.g:
      <a href="javascript:;" class="wayfinder-login">Institutional login</a>


    2. If you want Wayfinder to appear embedded in a div, use the wayfinder selector, e.g:
      <div id="wayfinder">Loading...</div>

      You should not set a height on the div or search results may overflow the available space.

If neither selector is found on the page, no error is displayed to the user but one is sent to the console. If both are on the page then the wayfinder selector will be used (embedded). 

Which should I choose?

It's up to you of course, but we would suggest that where your login function is in a small area of a regular page then the overlay is probably the better choice as searching for organisations can produce several answers. If your login function is on a dedicated page then the div version may fit in better with the UX and style.  Both will allow you to customise the labels - see the advanced options section below.

When testing, try some terms that will produce many results (such as University) and use the show more results button.  

Federations

The OpenAthens federation will be updated automatically but if you are in any other federations they will have to update your metadata to include valid discovery return URLs before Wayfinder can work for you: 

<idpdisc:DiscoveryResponse Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="http://connect.openathens.net/saml/2/auth" index="1"/>

Advanced operations

Some advanced information for anyone who needs a little more control

Logic flow

_wayfinder.options

These allow some changes of behaviour - add them to the end of the script bock you got from the dashboard - e.g:

<script>
    (function(w,a,y,f){
	...script block from publisher dashboard...
         )(window,document,'https://wayfinder.openathens.net/embed/','/loader.js');


    _wayfinder.options = {
        trigger: '.pre-existing-class',
		enableGeolocation: true,
		rememberCrossSite: true,
		ui: {
            titleText: 'Find your institution',
            summaryText: 'Your university, company or library',
            placeholderText: 'Institution name or email...',
            previousSearchUITitleText: 'Search for your institution',
            previousSearchUISummaryText: 'Institutions you\'ve selected before',
            previousSearchUISearchAgainText: 'Search for another institution...',
            previousSearchUIDeleteResultsText: 'Delete institution'
        }
    }
</script>


The options currently available are:

NTypeNotes
triggerStringIf you do not wish to use the default CSS selector name you can specify an alternative target or trigger (not both).
targetString
enableGeolocationBooleanIf omitted, or has any value other than true, geolocation hints are disabled.
rememberCrossSiteBooleanIf omitted, or has any value other than false, selected organisations are remembered for and from selections at other sites
uiObject
NTypeDefault text (en, en-GB)Notes
titleTextStringFind your institutionWhen undiscovered / no remembered organisation
summaryTextStringYour university, company or libraryWhen undiscovered / no remembered organisation
placeholderTextStringInstitution name or email...

When undiscovered / no remembered organisation

Appears in the search box

previousSearchUITitleTextStringSearch for your institutionWhere there are remembered organisations
previousSearchUISummaryTextStringInstitutions you've selected beforeWhere there are remembered organisations
previousSearchUISearchAgainTextStringSearch for another institutionWhere there are remembered organisations
previousSearchUIDeleteResultsTextStringDelete institution

Where there are remembered organisations

Appears in a button

If omitted or of zero length the default is used. If your text includes quote marks or apostrophes they will need to be escaped. 

The default text will use any relevant localisations we have uploaded.


buttonOptions

Object
NTypeDefault settingOptions
sizeString'medium'small

More options may become available in the future.

About Geolocation

Geolocation can help users select the correct organisation when none are shown, but means the browser will ask for permission when it hits any page with the Wayfinder javascript in the head. If Wayfinder will appear on multiple pages we recommend leaving this function disabled.

About rememberCrossSite

The default and recommended mode is to allow the organisation selection a user made elsewhere using Wayfinder to be reflected in your instance (and also the organisation selection made in your instance available elsewhere). This provides the best user experience, however you can turn it off with this option if you need to limit it to just remembering choices on your site - e.g. if the users commonly need to use a different IdP to access your site.

Customising the appearance

Retaining the default appearance of the embedded Wayfinder is encouraged as this provides a consistent user experience across sites (one of its goals). If you must change the appearance (such as when the colours clash with your brand), then you can override the styles for some key classes in your CSS. Here is an example:

Overlay button

The overlay version is invoked by a button which has three possible appearances and uses the .wayfinder-button class. The third one is for when Wayfinder remembers a user's previous selection, and has a .active class. Let's use three shades of blue in our example:

.wayfinder-button {
    background-color: #007bff !important;
}
 
.wayfinder-button:hover,.wayfinder-button.active:hover {
    background-color: #007ba8 !important;
}
 
.wayfinder-button.active {
    background-color: #0014ff !important;
}

(The !important bit is to ensure you override the default appearance.)