Drupal Forge Token
==================

The Drupal Forge Token module provides tokens for embedding Drupal Forge
launch widgets in Drupal 7 pages and text.

Requirements
------------

* Drupal 7.
* Token Filter is optional and is only needed to replace tokens in formatted
  text fields.

Usage
-----

Enable Drupal Forge Token. To place a widget, replace 71 below with the
numeric Drupal Forge template ID:

  [drupalforge:71]

To isolate the widget styles from the surrounding page, use:

  [drupalforge:71:isolate-styles]

When using the Replace tokens filter provided by the Token Filter module in a
text format, enable it and place it after the other filters in the format. If
you cannot place it after Limit allowed HTML tags, allow the
<webform-component> element and its templateid, relay-url, and stylesheet
attributes in that filter's Allowed HTML tags setting.

Relay configuration
-------------------

Widgets use the following relay URL by default:

  https://www.drupalforge.org/modules/contrib/embed_relay/relay.html

To override it, set the Drupal variable
drupalforge_token_relay_url. For example, with Drush:

  drush vset drupalforge_token_relay_url \
    'https://example.org/modules/contrib/embed_relay/relay.html'

The URL must point to a compatible relay page and be reachable by visitors
viewing the widget. Setting the variable to an empty string omits the
relay-url attribute, so the frontend makes requests without using the iframe
relay.

When the relay is used, it supports sign-in inside the widget and returns
visitors to the page where they started. This flow requires the page and relay
to use HTTPS. The widget asks the relay for a sign-in return URL and sends it
to Drupal Forge when launching or loading an application and when saving or
extending a submission. After sign-in, the relay completes the flow inside the
widget without requiring a page reload.

The relay host must allow these path patterns for webform requests:

  /form/starshot-quickstart
  /submission/*

It must also allow these cookie name patterns:

  template_*
  auto_save
  auto_extend

Relay errors are displayed in the widget, with details logged to the browser
console.

The variable can also be set in settings.php:

  $conf['drupalforge_token_relay_url'] =
    'https://example.org/modules/contrib/embed_relay/relay.html';

Changes made with Drush take effect after the normal Drupal cache rebuild.
