FragmentCreator

FragmentCreator is a CXT client that is adapted for the creation and editing of format-neutral fragments (see Introducing FragmentCreator).

The FragmentCreator is installed as a module on the FirstSpirit server. FragmentCreator then has to be explicitly assigned to a project. To do this, a separate web application must be defined for each project in the “Web applications” section (see below).

Conventional FirstSpirit projects cannot be configured as fragment projects at a later date.

Module file

fragment-creator-[version].fsm

Installing the module

The module is installed using the FirstSpirit ServerManager, in the “Server properties / Modules” dialog using the “Install” button:

(For more information about installing modules, see also Modules (→Documentation for Administrators).)

Creating a global web application

The web application must subsequently be defined and configured as a separate, global web application using FirstSpirit ServerManager in the “Web applications” area (button “Add” at “Configure global web apps”, see also Web applications (→Documentation for Administrators), paragraph “Installing global web applications”).

Adding web component

A suitable web server must be selcted for this global web application, subsequently the web component “FragmentCreator” must be added and then deployed (button “Install” / “Update”).

If the dialog is closed with “OK”, the “ApplicationPlugin: FragmentCreator (WebApp)” belonging to the Web component “FragmentCreator” will automatically be added to the Web application “Start page” (see page “Access via the FirstSpirit start page”, paragraph Area "Web applications" / "Start page"). This is necessary to display the icon enabling the FragmentCreator to be started via the FirstSpirit Start page.
The Web component must also be deployed there (button “Install” / “Update”).

Finally, the “ApplicationPlugin: FragmentCreator” must be added to the “Start page” area. See page “Access via the FirstSpirit start page”, paragraph Area "Start page".

Status page for error analysis

An incorrect configuration is a common source of errors. It can result in the software not functioning as expected or not functioning at all.

Under

/status

(appended to the URL of FragmentCreator), a status page can be reached which helps when detecting configuration problems, for example:

http://myServer:8080/fragments/status

Along with providing information about the server, the page also runs a test on the configuration and lists the most recent HTTP requests and log messages, as well as all currently registered MicroApps along with their accessibility, name, and URL.

In order to receive log messages, the logging.file.name parameter must be specified with the desired log file (e.g., /tmp/fc.log), for example:

logging.file.name=/home/tomcat/logs/fragments.log

The status page can only be accessed by administrators.

Note: To test accessibility, the status page sends an empty context to each MicroApp for checking. This can result in warning messages such as the following in the log:

de.espirit.cxt.microapps.stereotype.UnsupportedContextException: Context is not supported

Configuration

via web.xml

The web application is configured via the corresponding web.xml or via a properties file.
The placeholder values used by default do not work in every setup and should be checked and adapted to the respective setup.

Especially when changing the default value of the URL for the “FirstSpirit start page” web application fs5root (via the WEBAPP_ROOT_URL parameter), the automatic substitution for the ${FIRST_SPIRIT_URL} placeholder does not work (e.g. cxt.fragmentcreator.internal-url). In this case, the desired value must be specified manually.
(For more information on the WEBAPP_ROOT_URL parameter, see Web Applications (→Documentation for Administrators).)

Example: FirstSpirit Server, default configuration for cxt.fragmentcreator.internal-url in the web.xml:

<context-param>
   <param-name>cxt.fragmentcreator.internal-url</param-name>
   <param-value>${FIRST_SPIRIT_URL}/FragmentCreator/</param-value>
</context-param>

Module rolled out on the Tomcat web server (automatic substitution):

<context-param>
   <param-name>cxt.fragmentcreator.internal-url</param-name>
   <param-value>http://demo.e-spirit.de:2001/FragmentCreator/</param-value>
</context-param>

If the value for WEBAPP_ROOT_URL is changed, for example to WEBAPP_ROOT_URL=/fs5root:

<context-param>
   <param-name>cxt.fragmentcreator.internal-url</param-name>
   <param-value>http://demo.e-spirit.de:2001/fs5root/FragmentCreator/</param-value>
</context-param>

Comments

Comments are introduced by

<!--

in the web.xml.
This string can also be used to comment out parameters.

Communication

cxt.platform.firstspirit.hostname: Host name or IP address of the FirstSpirit server.

cxt.platform.firstspirit.port: Port of the FirstSpirit server.

cxt.platform.firstspirit.connection-mode: Connection mode for the communication with the FirstSpirit server.

• HTTP: normal Internet connection
• SOCKET: direct connection mode (default setting; Single-Sign-On in SOCKET mode only)

cxt.platform.firstspirit.connection-timeout: Time limit in seconds after which FirstSpirit connections are automatically closed when they are no longer used.
A value that is too low can cause users to be logged out unexpectedly. A high value, on the other hand, keeps many connections open when users close their browser without logging out.
Default value: 43200 (12 hours)

cxt.fragmentcreator.internal-url: The internal URL used by the platform to communicate with MicroApps, e.g.

cxt.fragmentcreator.internal-url=http://localhost:8080/FragmentCreator/

cxt.fragmentcreator.external-url: The URL with which users access the FragmentCreator via browser. This external URL cannot be determined automatically in every case and should therefore be configured manually. In most cases the following setting works:

cxt.fragmentcreator.external-url=https://external/FragmentCreator/

cxt.fragmentcreator.platform.internal-url: The URL of the CXT platform web application. If the platform and FragmentCreator are running on the same application server, a localhost address should be used, e.g.

cxt.fragmentcreator.platform.internal-url=http://localhost:8888/cxt-platform/

cxt.fragmentcreator.platform.external-url: The URL that users use to access the CXT platform web application via a browser. This external URL cannot be determined automatically in every case and should therefore be configured manually. In most cases, the following setting works:

cxt.fragmentcreator.platform.external-url=https://external/cxt-platform/

Authentication (OAuth and Eureka)

cxt.fragmentcreator.platform.eureka-password: Use here the password that you have assigned via cxt.platform.eureka.password in the configuration of the platform.

cxt.fragmentcreator.platform.oauth-client-secret: For authentication via OAuth, use the password here that you assigned via cxt.platform.oauth.client-secret in the configuration of the platform.

Content security policy header (CSP)

cxt.fragmentcreator.csp-origins: This parameter is used to adjust the Content-Security-Policy (CSP) HTTP header field of the Markdown Editor iframe. This is necessary, for example, if access to the Markdown Editor from other domains is to be allowed.
If the parameter is configured incorrectly or is missing, an error message is displayed in the browser console and the Markdown Editor is not opened.

This parameter can be used to define the origins from which access is to be possible. The fully qualified domain name is expected.
* can be used as a wildcard, e.g., to permit all URLs or certain subdomains of a domain.

Multiple entries can be specified separately using a space.

If the parameter is not specified, the default value 'self' is used. This means that only access from the same server is permitted (the same host and port).

Example:

cxt.fragmentcreator.csp-origins='self' *.e-spirit.de:8050

permits access from the domain from which the header is sent and from subdomains of e-spirit.de:8050.

Maximum file size for upload

By default, files up to 64 MB in size can be uploaded using the upload dialog in the FragmentCreator.

If necessary, this value can be adjusted using the following parameters in the web.xml file of the “FragmentCreator” module or in the cxt-fragment-creator.properties file:

• spring.servlet.multipart.max-file-size: Allowed file size for a medium that is uploaded via the upload dialog.
  The value must not be larger than the value for spring.servlet.multipart.max-request-size.
  For possible size specifications, see class DataSize (Spring Framework).
  Default value: 64MB
• spring.servlet.multipart.max-request-size: Each file is transferred in a separate HTTP request. Therefore, the value specified here must be at least as large as spring.servlet.multipart.max-file-size.
  For possible size specifications, see class DataSize (Spring Framework).
  Default value: 64MB

Markdown editor

Formatted texts are input in FragmentCreator via the FS_MARKDOWN input component (see also FirstSpirit Markdown Editor).
The input component is based on the external markdown editor, depending on the configuration

• “Quill” (https://quilljs.com)
• “SimpleMDE” (https://simplemde.com)

cxt.fragmentcreator.markdown-editor-type: This parameter defines which editor is to be used. “Quill” offers more WYSIWYG convenience and, therefore, a better user experience for the editor.
Currently, “Quill” is used by default. To use “SimpleMDE”, set the value of the parameter to simplemde.

Timeout for MicroApps registration

Registering MicroApps can take some time, especially in the case of restarting a FirstSpirit server or the Tomcat web server.
After a period of 10 min. the following error message is displayed when starting the FragmentCreator

x MicroApps could not be registered in a reasonable amount of time.

if the existing MicroApps could not be registered within this time, and the FragmentCreator is not started.

cxt.fragmentcreator.microAppRegistration.timeoutInMinutes: If required, you can adjust the timeout individually using this parameter.

Log outputs

Optional parameters can be configured for advanced log outputs.
See also Spring Boot Documentation (HowTo Logging).

logging.level: Spring Boot logs messages logs messages based on the content of the class path. By default, messages with the level WARN and higher are logged. For debug purposes, the level can be temporarily set to a lower level, however, using the prefix logging.level in the web.xml. This means, for example, that log outputs for CXT classes can be set to the DEBUG log level by specifying the de.espirit.cxt package, for example

<context-param>
    <param-name>logging.level.de.espirit.cxt</param-name>
    <param-value>DEBUG</param-value>
</context-param>

logging.file.name: This parameter can be used to write log outputs (for output to the console) to a file in addition, for example

<context-param>
    <param-name>logging.file.name</param-name>
    <param-value>/var/log/tomcat/cxt.log</param-value>
</context-param>

via Properties file

Alternatively, a properties file can be used to configure the FragmentCreator module (cxt-fragment-creator.properties). The configuration stored there overwrites all other properties (including the configuration via the web.xml file). During an automatic FirstSpirit update, the settings stored in this properties file remain unchanged and are not overwritten or reset.

To do this, first create a “config” directory in the classpath and then create a file

/config/cxt-fragment-creator.properties

When using Tomcat, place the file in the directory

${TOMCAT_HOME}/lib

The required parameters can be configured within the file, e.g.

markdownEditorType=simplemde

Deployment

The web application for the FragmentCreator configured as described above must then be rolled out on the selected web server using the “Installieren” button.

See also Web applications (→Documentation for Administrators).