Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Table of Contents
maxLevel3
minLevel3

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>

      Do not set a height on the div or search results may not display.

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.

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: 

Code Block
languagexml
<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

Expand
titleSee the information

Logic flow

Thumbnail of the 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:

Code Block
titleExample
<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 organisation',
            summaryText: 'Your university, company or library',
            placeholderText: 'Organisation name or email...',
            previousSearchUITitleText: 'Search for your organisation',
            previousSearchUISummaryText: 'Organisations you\'ve selected before',
            previousSearchUISearchAgainText: 'Search for another organisation...',
            previousSearchUIDeleteResultsText: 'Delete organisation'
        }
    }
</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 organisationUndiscovered / no remembered organisation
summaryTextStringYour university, company or libraryUndiscovered / no remembered organisation
placeholderTextStringOrganisation name or email...

Undiscovered / no remembered organisation

Appears in the search box

previousSearchUITitleTextStringSearch for your organisationWhere there are remembered organisations
previousSearchUISummaryTextStringOrganisations you've selected beforeWhere there are remembered organisations
previousSearchUISearchAgainTextStringSearch for another organisationWhere there are remembered organisations
previousSearchUIDeleteResultsTextStringDelete organisation

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, e.g. en-US will spell organisation with a 'z'.


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.