Edit File Drop-In Content Element

From this screen, you can edit and define a File Drop-In element.

See below for a general description of what drop-in elements are and how they are used.

A File Drop-In element has the following properties:

• Name: Enter a unique name for the drop-in. The name must not be used by any other drop-in. This name, surrounded by the matching opening and closing tags, defines the placeholder that must be used to include the drop-in content element in a message or in the text of another drop-in (as a nested drop-in).

• Description: Enter a description of the drop-in. Choose text that will allow you to remember what the drop-in is, and will allow others in your group (if applicable) to know what the drop-in means. Group members that do not have the right to edit and create drop-ins will only see this descriptive text. They will not be able to click on a drop-in to view its details because they do not have the right to create, modify, or delete drop-ins.

• Type: Click the drop-down menu and select the type of drop-in to use. You can change the type of a drop-in at any time. However, the type-specific data may be lost if you change the type.

• The drop-in contains: Select either Plain Text or HTML Text, depending on the type of content your drop-in contains.

  Plain Text drop-ins can be used both in plain text messages as well as in the HTML part or the alternative text part of an HTML message. The text will appear exactly as defined by the drop-in. Any HTML tags it may contain will not be rendered as HTML, but will appear verbatim.

  HTML text drop-ins can only be used in the HTML part of an HTML message. If the text of the drop-in contains HTML tags, then they will be rendered as HTML and not appear in the text.

• Any nested drop-ins are enclosed in: If the text of the drop-in contains a string enclosed in the opening and closing tags specified in the two edit boxes that follow this label, then the string between the two tags will be interpreted as the name of a nested drop-in. The entire nested placeholder (opening tag, drop-in name, and closing tag) will be recursively replaced with the value of the nested drop-in.

• File Name: Enter the name and path of the file that contains the text that will be used instead of the placeholder when this drop-in is used in the email content or as a nested drop-in. You must use a filename that is accessible from the server and not from your local workstation.
  If you want to include nested drop-ins inside of this drop-in, simply include the nested drop-in's name at the according location inside of the text in the referenced file, enclosed in the opening and closing tags specified in the Any nested drop-ins are enclosed in field.

• File Encoding: Click the drop-down menu and select the encoding that was used to save the text file referenced by the file name specified above.

Use the Test File Name link to preview the content of the file you have specified, with all nested drop-ins resolved (if any).

---

What is Drop-In Content?

Drop-in content is similar to text merging, where the same content is merged into the email message for all recipients.

The value by which a drop-in is replaced can either be user-defined (as explained here) or can be system defined (for system drop-ins).

Drop-ins can be used to create pre-defined content parts that can then be inserted into any message. For example, you could create drop-in content elements with your official company header and footer, and then easily add these to all your messages, simply by including their names in the content.

Drop-in content types that derive their text from an external source (for example, a file or a URL, see below), can also be used to create content that is inserted into the message at the moment of sending. This "just-in-time" content may be unknown at the time the message itself is defined. For example, you might create a drop-in that retrieves a stock quote from a certain URL. If you then create a message with that drop-in and schedule the email delivery for a future time, you will be sure that the most current stock quote is merged into the mail, and not the quote from the moment you created the content (or authorized the sending). This method ensures that your stock quote will always be up-to-date.

To include a drop-in content element into a message, simply type the drop-in element's name (with the exact spelling and case) and surround it with the opening and closing tags you have defined. This is called a "drop-in placeholder". For example, if you have a drop-in element with your company header, which you called "corp-header" (without the quotes), and you have defined the opening and closing tags "{{" and "}}", then you would include the placeholder "{{corp-header}}" into your content. This text would then be replaced whatever content you defined for your header in the body of the message.

You can define plain-text drop-in elements that can be included in any kind of content. HTML drop-ins can only be included in HTML content.

In the email message itself, the replacement of the placeholders with the actual drop-in element content happens just before the email is sent. You can define your message content, with all placeholders, at one time, and then schedule the email to be sent at a future date. The placeholders will not be replaced at the moment of scheduling, but just before sending, on the scheduled date and time. At that time, LISTSERV Maestro will determine the content of all drop-in elements it finds and will insert the content of the drop-ins, replacing the placeholders.

On the landing pages, the drop-in replacement happens at the moment the landing page is displayed in the recipient's browser or when the PDF landing page is downloaded. This replacement on the landing page happens anew each time the page is displayed (or downloaded). This has the effect, that if the content of the drop-in changes, then any subsequent access to the landing page will show the new content. This is true both for just-in-time drop-ins that get their content from a file, URL or a database, as well as for simple text drop-ins where the content is defined in Maestro itself. And this of course means that if a drop-in is later deleted, then from then on it will no longer be replaced when the landing page is viewed (but it is possible to create a new drop-in with the same name, so that the drop-in is once again replaced correctly on the landing page).

User-Defined Drop-In Element Types

There are four different types of drop-in elements available, all of which derive their content from a different kind of internal or external source:

• Text: The content of the drop-in element is derived from a static text that is defined by the user at the time of the creation of the drop-in. The placeholder will be replaced with this static text.

• File: The content of the drop-in element is loaded from a text file that is accessed by a file name that is defined by the user at the time of the creation of the drop-in. The placeholder will be replaced with the text that is found in this file exactly at the moment of the delivery. The file itself must be accessible from the server; it can not be a local file but rather a file available in the file system of the server.

• URL: The content of the drop-in element is loaded from a text file that is accessed by an http:// or ftp:// URL defined by the user at the time the drop-in is created. The placeholder will be replaced with the text that is found in this file exactly at the moment of delivery. The URL must be a URL that is accessible from the server, by the given protocol (http:// or ftp://). In some cases, for example, if firewalls are involved, a URL may not be accessible from the server even though it is accessible from the workstation of the user accessing Maestro. Keep in mind that this URL needs to be accessible from the server.

• Database: The content of the drop-in element is queried from a database. The database connection settings and the SQL select statement used for the query are defined by the user at the time the drop-in is created. The query is executed at the moment of replacement, and the content of the first column in the first row of the result set is converted to a text, which is then used to replace the placeholder.

File-type or URL-type drop-ins of the HTML type may also contain HTML tags that insert images into the text (<img> tags) with a file name. The corresponding image will then be loaded and sent as part of the message, as an "inline-image". In this case, access to the image file/URL must have been allowed by the administrator, just as for the text file of the drop-in itself (see below).

To embed an inline image into a file-type or URL-type drop-in, simply include the image's file name as a relative path (relative to the location of the drop-in page), for example <img src="images/sample.gif">. For file-type drop-ins, you may also include the image's file name as an absolute path (in Windows this would include the drive-letter), but then you need to remember to include the "file://" protocol, for example: <img src="file://C:\sample\images\sample.gif">.

Image tags that reference images by absolute Web URLs are possible too, and can be used in any drop-in of the HTML type. Images that are embedded by absolute Web URLs (usually starting with http://) are not sent along with the email as inline images; instead, they are sent as "linked images", meaning that the sent email will contain only references to the images on the Web.

Drop-In Element Recursion or Nested Drop-ins

The text of a drop-in element (no matter the source from which it is derived) may in turn contain placeholders with the names of other drop-ins. Before a placeholder is replaced by the matching drop-in's text, that text is first scanned for further placeholders. If any are found, then they are replaced first. If during these replacements further nested placeholders are found, then they are replaced too, and so on, until no more placeholders need to be resolved.

When using nested drop-in placeholders, be careful not to create an endless recursion by using the name of the placeholder within the content of the drop-in. A drop-in may not contain its own placeholder name. Similarly, recursive loops, like "A contains B and B contains A" (or even longer loops with several nested drop-ins), are not allowed. If during the chain of nested drop-in replacements a drop-in is encountered that has already been replaced earlier in the same chain, then Maestro will generate an error and your email job will not be delivered.

Testing Drop-Ins

Depending on the type of a drop-in or how its content is defined, there are several circumstances that may make the replacement of a drop-in fail:

• If the drop-in contains other drop-ins in a nested endless recursion loop, then the replacement will fail.

• If a drop-in is of the HTML type, but is included either in a plain text message or in the alternative text of an HTML message, then the replacement will fail.

• If a file-type drop-in is defined with a file name for which no file can be found on the server (or the file is not accessible for some other reason), then the replacement will fail.

• If a URL-type drop-in is defined with a URL that is not accessible from the server, then the replacement will fail.

• If a database-type drop-in is defined with database connection parameters that cannot be used to connect to a database, if the database is down, or if the SQL query does not result in at least one row with at least one column, then the replacement will fail.

Because of these circumstances, and because you will want to preview what your drop-in looks like, all drop-in definition screens contain an option to test the current drop-in. This will display the content of the drop-in at the moment of the testing, with all nested drop-ins (if any) resolved. If the drop-in replacement has failed, then an error message will be displayed.

Multiple Drop-Ins

You may use any number of drop-in placeholders in the email content or in the text of other drop-ins.

You may even use the same drop-in placeholder several times in the same content (although not in a way that would lead to an endless recursion loop, see above), or even in different parts of the same message (for example the HTML part and the alternative text part of an HTML message).

If the same drop-in placeholder is used several times in the same message, all occurrences of this placeholder will be replaced with exactly the same text. The source that defines the drop-in will be accessed only once, and the result will be used to replace all placeholders of the same name for the entire message.

Access Restrictions

Before using a file-type or URL-type drop-in, the system administrator will need to configure certain files, folders, and/or URLs on the server and make them available to use with drop-ins and accessible to you. This configuration is to prevent security breaches to the system. To access a file on the server without any security measures would open the possibility for access to confidential files on the server and include their content in a message. Similarly, accessing a URL from the server could allow access to URLs (for example, on an intranet) that are normally not accessible (for example, they are protected by a firewall, but the server is behind this firewall).

To help avoid such security holes, Maestro, by default, does not allow you to define working file-type or URL-type drop-ins until the administrator configures the files, folders, and URLs associated with them. If you are experiencing difficulty with these two drop-in types, then check with your system administrator.