Adding placeholders to custom widgets
Custom widgets can also take advantage of non-schema field placeholders by adding code to the widget module in question, preparing the widget template to show the custom placeholder content, and adding the placeholder content into an accessible folder.
Basic placeholder addition
In order to add a custom image file, two options should be set within the widget
placeholder: true and the
placeholderImage option with the value set to the file extension of the placeholder content without any
Next, to supply the URL of the placeholder content, the module should invoke the
determineBestAssetUrl('placeholder') method in the
init(self) initialization function.
Even though the option name ends with
Image, this same method can be used for adding custom video placeholder content that will be uploaded into the module's
public folder. In contrast, for videos that are hosted externally, you need to add the
placeholder: true and
placeholderUrl option with the value set to the URL of the resource. The initialization function in this case can be skipped.
Example for adding a custom image.
You can bypass the call to
determineBestAsetUrl() for your images or videos stored in the
public folder and instead pass the path to the asset using
placeholderUrl in place of
placeholderImage. This is discouraged because errors can be made in this path. It is better to let Apostrophe figure this out for you.
Altering the widget.html file
The specific alteration of the
widget.html template will depend on the type of placeholder content being delivered. Irrespective of file type, the template will have access to
data.manager.options.placeholderUrl to populate the markup.
data.widget.aposPlaceholder, allows for confirmation that the placeholder should be displayed. This will return
true when the widget is first added and return
false once the widget has been edited.
data.manager.options.placeholderUrl, will contain the path to the content placeholder asset. If you set the
placeholderImage, this will either be the path computed by the call to
determineBestAssetUrl(). Otherwise, it will be the URL passed directly through the
This example demonstrates adding an image.
This example demonstrates adding a self-hosted video.
Add the placeholder content file
Your placeholder content should be added to the
public folder of the custom widget. It should be named
placeholder.extension, where the extension matches the extension passed into the
placeholderImage option. In the first example above, the file should be
Adding a placeholder with a custom name
In some cases, a widget might need to have more than a single piece of placeholder content, or you might want to give the placeholder content a different name than
placeholder.extension. In this case, once again you need to modify the main module options, the Nunjuck template, and the contents of the public folder.
index.js file for custom placeholders
As with the basic addition of a placeholder, for one or more custom placeholders the
placeholder option should have a value of
true. Next, the extension of any project-hosted custom placeholders should be passed in an option of
<name>Image. For example,
customOneImage: 'png' and
customTwoImage: 'png'. For any videos that are not uploaded to the project, the URL can be added to an option of
<name>Url, for example,
For each self-hosted placeholder, the initialization function should call the
determineBestAssetUrl() method, with the name of the placeholder passed as an argument. For example
self.determineBestAssetUrl('customTwo'). This is not required for assets using the
If electing to add multiple placeholders to a single page, as soon as the user makes any edits, all placeholder content will be removed from the page because
aposPlaceholder is only checked once to determine if the widget has been edited.
Altering the Nunjucks template for custom placeholders
The template will still have access to
data.widget.aposPlaceholder to determine if the widget has been edited and remove placeholder content. The URL for the placeholder can be accessed using
data.manager.options.<name>Url. For example,
data.manager.options.videoOneUrl. This will be available for each
<name>Url option in the module.
The same conditional block that was used for a single basic placeholder should be used for each custom placeholder added to the template.
Adding files for custom placeholders
All of the self-hosted custom placeholder assets should be copied to the module's
public folder. The file names and extensions should match the options passed to the main module file. For the example above, this would be