utexas/utexas_qualtrics_filter

Custom text filter to allow Qualtrics forms into WYSIWYG fields

4.0.0 2024-06-03 16:56 UTC

Requires

• composer/installers: ^1.0 || ^2.0

GPL-2.0-or-later

• drupal

README

This is a Drupal module that provides a text format filter to embed Qualtrics forms into WYSIWYG fields.

Full documentation can be found at https://drupalkit.its.utexas.edu/docs/content/embedding_qualtrics_forms.html

Expected shortcode syntax for text format filter

Provided shortcode syntax of the following pattern:

[embed]URL_HERE | height:HEIGHT_HERE | title:TITLE_HERE[/embed]

The text format filter will output the following:

<iframe src="URL_HERE" scrolling="auto" name="Qualtrics" title="TITLE_HERE" class="qualtrics-form" id="Qualtrics" width="100%" height="HEIGHT_HERE" frameborder="no" align="middle"></iframe>

The title and height values are optional.

Development and Stewardship Notes for CKEditor plugin

In addition to providing a text format filter that converts shortcode syntax into iframe markup, this module includes a CKEditor plugin with a form, in a modal, for inputting Qualtrics information.

Read first

• Drupal's CKEditor 5 architecture: https://api.drupal.org/api/drupal/core!modules!ckeditor5!ckeditor5.api.php/group/ckeditor5_architecture/10.0.x
• Drupal's API for working with CKEditor 5: https://www.drupal.org/docs/drupal-apis/ckeditor-5-api/overview
• "CKEditor 5 Dev Tools" (https://www.drupal.org/project/ckeditor5_dev/) includes a starter template with useful inline comments about naming.

The CKEditor 5 version of this plugin was created by the WCMS team in 2022. The plugin itself is largely based on the example Abbreviation Plugin, version 2.

While plugins can be written in plain JavaScript, all documentation uses Typescript. The Typescript files must be compiled for use as a plugin, and require a specific compilation process to be integrated as a standalone plugin within Drupal's CKEditor instance.

Custom plugins can be developed outside of the context of Drupal following the model at developing custom plugins. A custom inspector to help examine the model and view of the CKEditor interface. However, for integration within Drupal, the compilation process provided in the generic CKEditor documentation will not work; rather, you need a DLL build that will create a standalone plugin.

Development

To make modifications to the Qualtrics plugin itself:

1. Add and install this module in a Drupal site as you would normally.
2. cd into js/ckeditor5_plugins/qualtrics
3. Make desired changes in the src/ directory.
4. Run the following commands to build the distributable JS:

npm install
yarn install
yarn run build

1. Run drush cr

Architectural overview

├── index.js --> Entrypoint for build process (nonfunctional)
├── src
│   ├── qualtricsform.js --> Business logic for rendering & validating form
│   └── qualtrics.js --> Business logic for displaying the button & downcasting
└── theme
    ├── css
    │   └── form.css --> Minor tweaks to the form in the modal
    └── icons
        └── qualtrics.svg --> The plugin icon
├── build
│   └── qualtrics.js --> The DLL, used by CKEditor