The Advanced tab of the Universal Content Puller edit dialog provides further options common to all UCP source/trandform/display workflows.
The Support tab provides sources of further support and also useful Export and Import tools for UCP settings.
There are two broad reasons for AJAX loading pulled content. Performance and Interaction.
By default, UCP loads pulled content directly into a page. The alternative is to delay pulling the content until after the page has loaded into the browser and then load it by AJAX. For example, a content source could be a little slow responding or so complex or image heavy that it creates an unwanted delay in the web server.
An example of interaction would be to only load content in response to a user interaction elsewhere on a page. For example, a user clicks a button for more details and the detailed content is then loaded.
UCP supports variations of both of these use-cases.
Load with page - no ajax
Loading directly with the page, no AJAX, is the default setting for a very good reason.
Ajax load immediately
The pulled content is loaded immediately the page has rendered in the browser.
Ajax load after delay
After the page has rendered in the browser there is a configurable delay before the the pulled content is loaded. A delay of 0ms is the equivalent of loading immediately.
Ajax lazy load on proximity to viewport
Proximity is adjusted by a setting a proximity in pixels. When the browser is scrolled or resized to bring the container for the pulled content within that proximity of the viewport the pulled content is loaded.
As a guideline, allow about half the anticipated window height and adjust that depending on how long you expect ajax loading the pulled content to take. To present a seamless experience to users, you want pulled content to begin loading sufficiently far ahead in the page scrolling to have completed by the time the user gets to it!
Ajax load when visible
There is a subtle difference between proximity to viewport and visibility. A pulled content container could be visible but outside the viewport, or hidden even when inside the viewport. For example, a set of tabs or accordions could be inside the viewport, but all except the first tab or accordion panel would not be visible until that tab or accordion is opened.
When the pulled content container becomed visible, the pulled content is AJAX loaded.
Ajax load when placeholder clicked
UCP provides a configurable placeholder that is shown until the pulled content is AJAX loaded. This setting turns that placeholder into a clickable element, loading the pulled content when it is clicked.
Placeholder options are
- No visible placeholder - so not much use with this AJAX option.
- Blank area - with optional label.
- Outlne area - provides a faint outline with an optional label.
- Default - a Bootstrap .well with a label.
The label and height of the placeholder are also configurable.
You can further style the placeholder with CSS targetting the class .ucp-ajax-placeholder
Ajax load on ucp_load event
A further event, ucp_loaded, is triggered by UCP whenever content has been successfully loaded by AJAX. ucp_loaded is always triggered, irrespective of the AJAX option.
Rather than heading off to the concrete5 provides a convenient interface to settings available in block edit menu > Advanced. You can conveniently manage block cache settings directly in the UCP Advanced tab.
Choice of block cache settings depends greatly on what content is pulled. For example, if pulling content from a bulky or slow external URL that doesn't change often, you may want to enable all options and set the cache for a long lifetime. On the other hand, if you are pulling data that changes dynamically and need it to be up-to-date, you would likely only want a shortt cache lifgetime or to leave it disabled.
After changing cache settings, remember to check the page both immediately after publishing and later, and while logged out. You don't want an over-indulgant cache setting revealing content that should not be available to casual visitors.
Be careful with cache settings if pagination is enabled.
Sanitize and Niceify
- A source where you don't have control over the content or security, so could be used by a third party to attack the security of your site.
Sanitization can be selected at settings:
- Safe and Styled - As safe, but allowing syles.
- Basic elements - Only allowing elements p, br, strong, em, strike, a
The converse of sanitizing is that content may contain URLs for other pages or images that are not already rendered as clickable links of shown as images.
Autolinking is the process of taking text URLs found in the page and turning them into clickable links. Autolinking is not a perfect process, so UCP provides two mechanisms for autolinking:
- The concrete5 core autolinker. This works best with plain text. When applied to HTML it will corrupt existing links.
Both autolinkers can be configured to link to the same window/tab, or to a _blank tab.
When the advanced autolinker is selected, a further option is to render image URLs as either links to URLs or as image elements to show the image, using any configured concrete5 thumbnail size. Beware that thumbnail sizes are for sizing compatible with the site theme and do not actually resize the linked image file. External images are not resized and may be very big.
By default, UCP wraps all pulled content with
The advanced options for the wrapper allow the wrapping element and/or class to be changed, or even to disable wrapping altogether. When there is a wrapping element, UCP will always ensure the classes rendered include the class 'ucp-body'
For example, you could change the wrapping element to a
<blockquote class="my-quote-class ucp-body"></div>
Here we have settings that are best left alone unless you know what you are doing.
Edit mode marker
UCP will normally only show a marker when in edit mode without actually pulling content, so that nothing in the pulled content can interfere with the ability to edit the page.
The edit mode marker includes some basic information about the configured content source, transform and display.
If you are confident that content will not interfere in any way, you can turn off the edit mode marker and get a clearer view of what is being pulled.
When pulling content that itself pulls content, you could inadvertently create a loop that continues in ever continuing cirlces of recursion that eventuslly cause a server error.
UCP includes built in recursion protection and will report when recursion is detected with an error message on the page. If you don't want vistors to see that, you can turn it off the message. Recursion will still be detected and logged, but will not be shown on the page.
Nevertheless, if you try hard enough you may be able to create a convoluted loop of recursion that UCP is unable to detect and that will subsequently lead to a broken page.
If that happens, you may
- Revert the page version from the dashboard sitemap.
- Set 'panic' to true in the UCP config settings at application/config/generated_overrides/jl_universal_content_puller.php. This will render all UCP blocks as markers while you edit the offending block and fix the problem.
Import and Export
The Support tab of the UCP edit dialog provides buttons to Export and Import settings. Settings are exported as JSON data which can then be imported to other UCP blocks.
To some extent, Export and Import can even be used to copy UCP settings between sites, though take care as any page or file IDs in the JSON may not map accurately between sites and will need editing for the desired copy to work.
Further documentation and support
When requesting support, it may help if you copy the UCP settings using the Export button on the Support tab of the dialog.