Embedding a Form in an External Wrapper Template

Owned by Former user (Deleted)
Last updated: Apr 13, 2015
5 min read

Description and Use Cases

Using the forms engine you can embed a form you create in an external wrapper or template hosted outside the forms engine.  This could be used to have elements surrounding your form (navigation, news bulletins, headers/footers) update as they are updated on your web site.  Embedding in this way would be particularly useful for:

  • Sites managed in a CMS such as Cascade

  • Sites managed by template-driven editors such as Dreamweaver

  • Dynamic sites such as Drupal or WordPress

  • Situations where you want a content editor to manage content around the form without having access to the form itself

Important Considerations

There are a number of factors to consider before deploying an external wrapper:

Common Shared Assets

The form you build must use the same shared assets (CSS, images, JavaScript) as the external template.  For example, if you use the sample HTML documents to create your form those rely heavily on Bootstrap and the forms jQuery plugin and will not work if the external wrapper does not include those same assets.  

One way to solve this is to build the form in the wrapper page or some trimmed down version of it from the outset rather than using the static assets provided by the engine.  An alternative approach is to reference the static assets in your wrapper template, though you should take care that these assets don't conflict with assets in your wrapper template.  Bootstrap will almost certainly interfere with your CSS if you aren't already using it, though the jQuery plugin should not.

When the form is presented to the user it will be presented on the www.forms.northwestern.edu host.  Any assets or linked pages you reference in your template through a document- or root-relative link will not display correctly when presented.  One approach is to use a base tag at the beginning of your wrapper setting the base back to the location of your wrapper.  Another approach would be to use all absolutely-qualified URLs however that might be impractical with some sites.

Mixing Secure and Insecure Content

The engine requires https when filling out forms.  If your assets are not behind https older browsers (IE8 and older especially) may give the user a warning when rendering the form or not include the insecure assets at all.  One approach is to publish your wrapper to a host that supports https even if you don't require https for every-day browsing.  

Of course another approach is to not support older browsers as a matter of policy.  In this case you could create a warning message in your form or wrapper that uses inline styles but is hidden by a rule in your linked style sheets (i.e., if the browser includes the CSS this message will be hidden, if the browser does not the user will see the error.

Same-Origin Policy

If your wrapper is doing something that would not be allowed under the same-origin policy (e.g., using XMLHttpRequest) those calls would fail when the page is rendered on the forms host.  Potentially this could be solved in modern browsers with cross-origin resource sharing (CORS).

Process for Embedding Forms

When your form is rendered using an external template to following steps take place:

  1. The engine requests your external wrapper

  2. The engine inspects the DOM and looks for the div with the #form-container id

  3. The contents of the div are discarded

  4. The engine inspects the DOM of the form uploaded to the system as it would be presented to the user

  5. The contents of the #form-container div in the form are injected in to the #form-container div of the wrapper

  6. The resulting document is presented to the user

Creating the External Wrapper

The external wrapper should be an accessible (but perhaps unlinked) page on your site with a #form-container div where you want the form injected.  Since the contents of this div will be discarded you can put a message to your web editors like “Embed Form Here.”  You could also put a meta- or JavaScript-refresh forwarding users to the location of the form in the engine.  That way any users who stumble upon the wrapper are forwarded to the real form. Using this technique you could also link to the template directly in your site.

Linking the Form to the Wrapper

When uploading the code of your form (or editing an existing version) set the External Wrapper URL to your external wrapper.

Errors

The engine does not validate your external wrapper at the time that you set the URL.  The forms engine will return the user attempting to fill out your form a 404 Not Found if it does not find the #form-container div in your wrapper.  If your server returns something other than your wrapper, such as a 503 Temporarily Unavailable, the form engine will still return a 404 to the user (unless the error your server returns includes the #form-container div in it's HTML).

Potential Methods to Integrate with Cascade

Cascade is a commonly used tool to manage web sites at Northwestern and a good use case for an external wrapper as described above.  One approach to integrate the two is the following (assuming you have some generic page components).

Cascade Setup

  1. Create a new Form Asset metadata set based off of your standard metadata set.  Add a new dynamic field, form_url, with label “Online Forms URL” that is text, required, and inline.  Add a new dynamic field, base_url, with label “Site URL After Publish” that is text, required, and inline.  

  2. Create a new Form Page template based off of your standard template. Add a FORM-BASE region to the top of your <head> and a FORM-EMBED region where you want the form to be embedded.  Putting if you after DEFAULT will allow your users to edit text above the form.

  3. Create a new Form Page configuration set based off of your standard configuration set but linked to the Form Page template

  4. Link the FORM-BASE region to a block that can access the base_url metadata field created above with a format that translates the URL in to a base tag when published (e.g., form-base.xsl) 

  5. Link the FORM-EMBED region to a block that can access the form_url metadata field created above with a format that translates the URL in to a JavaScript redirect when published but displays a message to the user while in Cascade (e.g., form-embed.xsl)

  6. Create a new Form Page content type based off of the Form Page configuration set and the Form Asset metadata set with your standard data definition

Using the Form Content Type

  1. Create a new asset using your standard page factory

  2. Switch the content type to the new Form Page content type

  3. Provide the value for the Online Forms URL and the Site URL After Publish

  4. Publish your page

You could optionally create a new base asset and asset factory for this content type.  This example does not implement that because (a) it is likely to be a rarely used factory and (b) using it properly requires insight in to the forms engine to provide the URL so additional requiring the application of the content type isn't adding much complexity (i.e., everyday editors won't be able to set up the form itself, only a power user can and they can also understand content types).