Transforming UB’s digital communications.
External Embed Component
Integrate third-party content (e.g. external scripts or databases).
For developers only!
The DCT Help Team does not support third party code.
Don't be misled by the name.
HTML Snippet is usually a better tool to host content from third party apps.
On this page:
Accessibility
- Custom code must be accessible.
- Third party content must be accessible.
- Font size and contrast.
- Link text should be meaningful.
- Images require Alt text.
- Let users control animations.
When you use this component, your team commits to maintaining the security, accessibility, and stability of any linked site or code.
Last reviewed: December 12, 2023
Overview
If you have Web-accessible scripts that need to run on a server, especially if they are services your website provides, rather than tools to help manage the content of your website, they belong on a separate server from the CMS. This could be the server they're already on, Wings, a server you manage yourself, or in the cloud.
To present these external services in the context of your UBCMS site (header, footer, navigation), you can use the "External Embed" component. This is almost like an iframe, but runs on the server side and is relatively unnoticeable to the website visitor.
At the point on the UBCMS page where you add the External Embed, your external application will be requested and embedded into the page. This is designed to work even if your application has multiple pages and embedded resources that link among each other.
In addition to the External Embed component, you could also use HTML Snippet components to embed HTML and JavaScript in your UBCMS page that are coded to interact with your external application via AJAX or similar techniques.
Examples of these techniques already in use include:
- The SMBS Faculty Browser (http://medicine.buffalo.edu/faculty.html), which is actually a bunch of ASP scripts on a separate backend server, including the profile pages, different tabs and search.
- The Parking and Transportation Mobile page (http://mobile.buffalo.edu/more_ub_mobile/transportation.html), which uses some AJAX techniques to add highlighted alert markers (the red number "2" right now) to a few links if there is more info available in a back-end application, and then (if you click one of those links), uses an External Embed component to display the external content within the UBCMS page.
- The Services Status dashboard on the UBit home page (http://www.buffalo.edu/ubit.html), which is an External Embed.
Using This Component
There are three tabs: External, Filters and Wrapper. Click the wrench icon to configure these settings.
Technical Restrictions
- Only experienced developers should handle this component.
- Be sure to carefully test your code for major bowsers before integrating into the UBCMS.
Test carefully!
You may break your page unexpectedly and the Help Desk does not support custom code.
Configure - Main Settings
External Tab
The component opened for editing showing the main 'External' tab.
Target application - Provide the source URL of your third-party application that will be embedded.
Rewrite limit - Define how the embedded content will perform when a link is clicked.
- No limit - All clicks will stay within the UBCMS page.
- This option is not very safe since potentially non-approved content may then be shown as if it were actually part of your own site.
- Host - Clicks outside your application's server will leave the UBCMS page. This is good for multi-page applications.
- Off - ALL clicks will leave the UBCMS page. This is good for simple content.
For Pages With Multiple Embeds...
When more than one External Embed component is on the same page, Rewrite limit should be set to 'Off' to avoid conflicts (e.g. a 'not trusted' error).
Pass parameters - Allow the Web application to pass parameters from your UBCMS page (e.g., for search queries or forms).
Component handle - Choose to display the component's gray bar and descriptive label in Author (recommended).
Description: Enter a descriptive label for the component that will be shown on your page in Author (recommended).
Timeout (ms) - Define how long the UBCMS should wait for the external server to supply your embedded content (default is 20,000 or 20 seconds).
Error content - Display this page on your UBCMS site if the external content cannot be displayed.
Filters Tab
The component opened for editing showing the Filters tab.
Click the button with the plus (+) mark to define any regular expressions and replacement patterns for the application. This can be used to adjust the code supplied by the external application, but ideally any adjustments would be made on the external application.
Wrapper Tab
You may type or paste HTML to be included before and after the application’s HTML. (Ideally you would instead set this up in the external application itself.)
Additional Notes
When creating the third-party application:
- Server caching. Be advised that the UBCMS has server side caching. Pages are normally stored until there is a change by an author, and changes in an externally embedded third-party application do not qualify as an author change unless they include a form or parameters are passed. Workarounds include:
- Set the page to never be cached.
- Add -nc to the page's name (e.g. /content/www/yoursite/yourpage-nc.html.)
- Or ask us to add your page to a "never cache" list.
- Manually (re)activate any page on your site to clear all of your site's pages from the cache, including your external embed page(s).
- Set the page to never be cached.
- Be careful with links – relative links may break.
- Skip the header and footer – these will always be supplied by the UBCMS host page.
- SSL - Be careful if your third party content needs to be accessed securely. Your main page may be insecure and this will cause a browser security conflict.
- Forms - POST and GET both work.
- Cookies – will NOT be passed through.
- HTTP headers – will NOT be passed through.
- Authentication – will NOT be passed through (e.g. Shibboleth credentials).
- If authentication is used on the UBCMS side, the credentials (username,
etc.) will not be passed to the external application. - If the external application requires authentication (Shibboleth,
cookies, http basic auth, etc.), it will not work in a UBCMS external embed
because this data (cookies, headers) are not passed through.
- If authentication is used on the UBCMS side, the credentials (username,
- Redirects – these should work normally.
- Errors – Any server or script errors will be captured and displayed within the UBCMS page (Demo Site examples).
Consider how this custom code will display in smartphones and other small screen devices.
Consider how this custom code may impact page performance.
Accessibility Concerns
Authors are responsible for any custom adjustments they make to their UBCMS pages. This includes code added using External Embed or HTML Snippet components, or introduced through page Properties.
Best practice: only a developer should modify the standard UBCMS code or styling, and any adjustments should be made thoughtfully, with regard for accessibility and long term maintenance.
Authors are responsible for any third party content that is hosted or linked from their UBCMS pages.
This includes applications such as Formstack forms and Google Maps, that are displayed using their own component, as well as entries from UB's Calendar of Events, and external content hosted using HTML Snippet or External Embed.
Best practice: for Formstack forms, avoid using the date picker and the 'other' option in dropdowns.
Best practice: for the HTML Snippet and External Embed, always run an accessibility test (e.g. using a browser extension), check its behavior in mobile, and consider how it may impact page performance in general.
Best practice: if your code relies on a 'div' or iframe to house its content on your page, it must have an identifying label, often coded as a 'aria-label' or sometimes a 'title', that assistive technology can see. Formstack produces a title automatically, although it is poorly worded, but other applications tend to skip this requirement so it must be added manually on your end.
If you have concerns that external vendor content is not accessible, please contact UB's Web Accessibility officer.
Additional Reference:
Accessibility includes the legibility of text on our pages. Font sizes and the contrast between text and background must be great enough that people with reduced eyesight can read the words.
The UBCMS system-wide fonts and our UB Brand colors are optimized to meet ADA and Web standards (more about our new brand palette).
Best practice: Please do not adjust our standard fonts or introduce new palettes using custom CSS.
Link text should describe where the link will take the user in a manner that is appropriate to the context on your page and also the target page. This is also true for images that act as links.
Best practice: Avoid meaningless standalone phrases like "click here", "see all" and "learn more".
Additional Reference:
Alternative text ('alt text') is a short, written description that describes the appearance, content and/or function of an image on a webpage. Adding alt text is a best practice for all your UBCMS images and is required for accessibility so users will understand what they are not seeing.
Purely decorative images (that do not convey content or have a function on the page) can instead be set as "This image does not require Alt text" in some components, which also nullifies alt text that was previously entered.
Alt text is required in these contexts:
- If the image is a link. *
- If the image is zoomable.
- If the image depicts important information not clearly provided in a caption or nearby text on the page.
- If the image has a function; e.g. for navigation -- 'next slide'. *
- For the static thumbnail images that are generated by Video and Flex Module components.
* When the image is a link, starts an animation or video, or is a navigational element, alt text should indicate its function, not the image's content (i.e., "watch video ABC" and not "screenshot from video ABC"). Screen readers will treat this image as a standard link.
Alt text can be added to images in Assets. This is required for images that are then used in the Photo Gallery component, while it can also be used as an alternate source for Alt text in some components (e.g. the Photo setting 'Get Alt text from Assets').
Best practice:
- Screen readers automatically announce "image of...", so you do not need to include the word "image" or "graphic" in your alt text.
- Add a final period so screen readers will pause before reading the rest of the page.
- Be concise (under 150 characters) but include any significant elements to the image, e.g., "student using microscope in a research lab."
- If the image is used for navigation, describe what will happen, e.g. "next page of results".
- If the image is a link to another page, name or describe the target page (e.g., "School of Nursing.") but do not say it is a link -- screen readers indicate that as well. This also applies to zoomable Photos.
- If the image is a link that starts a video (named ABC), consider "YouTube video entitled ABC." or just "watch ABC."
- If the image contains a lot of text (e.g. a chart or table), provide this information in other ways on your page, perhaps as a nearby collapsible container labeled appropriately.
- Alt text should be added whenever images are uploaded into Assets.
Text Over Photo provides an accessible alternative to using images that have embedded text.
> Learn more about the Text Over Photo component.
Known Issues
Additional Reference:
The user should control carousels, slideshows and video, so they are not confused by unexpected behavior and to provide enough time for them to process each segment.
Best practice:
- Do not auto-start video.
- Do not automatically scroll a carousel or slideshow.
- Provide tools that allow users to start, stop and resume animations.
These recommendations are supported by default in UBCMS carousel, slideshow and video components. Please comply with this best practice if you embed external video or animations.