Reusable Content & Text Blocks WordPress Plugin 2017-11-18T08:15:16+00:00

Documentation – Reusable Content & Text Blocks WordPress Plugin

Loomisoft’s Reusable Content & Text Blocks plugin allows you to define modular and repeated blocks of text and other content and place them within pages, posts, sidebars, widgetised areas or anywhere on your site via shortcodes, via the provided widget or via PHP.

The idea behind this plugin is two-fold. The first is to modularise repeated content so you can use the same content in multiple pages, posts and other places, which will allow you to change the relevant content in just one place rather than in dozens of pages and posts. The second is to provide an easy way to add complex custom content within sidebars and widgets. Being compatible with WPBakery’s Page Builder (formerly known as Visual Composer), Avada’s Fusion Builder, Beaver Builder and SiteOrigin Page Builder means that embedded blocks can have a richer range of elements, layout and styling.

This page serves to give detailed usage information and examples. For a more general overview information about the plugin, click here.

Installing the Plugin

Available from WordPress.org, the plugin can be installed in two ways:

  • From your WordPress website’s administration menu:
    • Click Plugins > Add New
    • Search for “Loomisoft” and locate the plugin
    • Click “Install Now”
    • Activate the plugin

Once the plugin is installed and activated, you’re good to go!

Managing Content/Text Blocks

Adding/Editing/Deleting Content Blocks

Content or text blocks can be added and managed via the custom “Content Blocks” post type in the same way that the normal WordPress posts and pages are … you can add new content blocks, or edit or bin existing blocks in exactly the same way.

Content Block Contents

Each content block has three main elements:

  • Title: This is more for your reference and more for labelling purposes
  • Content: The actual content of each block can be managed in a similar way to normal pages and posts. You can use the normal WordPress TinyMCE editor or one of the page builders listed below.
  • Visibility: For a content block to be displayed, it must be set to “Published”. This gives great control over whether a block is displayed. Content blocks may even be set for publication at a future date and time.

Once you are happy with the block, just save it.

If you are amending an existing content block, the relevant changes will take effect immediately wherever the block is used. However, note that if you are using any cache plugins, you might need to purge caches before changes are reflected on the site.

Page Builders

Not only can you use the generic TinyMCE editor for putting content in a block, you can also use page builders such as WPBakery’s Page Builder (formerly known as Visual Composer), Avada’s Fusion Builder, Beaver Builder, SiteOrigin Page Builder. Other page builders may, in principle, also be compatible.

In order to do so, for the specific page builder, enable the “lscontentblock” or “Content Blocks” post type within its settings. Also, when your content block contains content from a page builder, you must call (embed) the block with “full content filtering” or the PARA parameter set to “full”. See section below for full information regarding content processing and the PARA parameter.

As at the time of the publication of this documentation, the plugin has been tested with:

  • WPBakery’s Page Builder version 5.4.2
  • Avada’s Fusion Builder version 1.2.2 (with Avada version 5.2.2)
  • Beaver Builder version 1.10.9.2
  • SiteOrigin Page Builder version 2.5.14

Placing Content Blocks Using Shortcodes

The simplest way to embed content blocks within posts and pages is by using shortcodes. In fact, shortcodes can be used outside of the main content area so long as the theme you use performs shortcode processing in those areas.

The basic shortcode syntax is as follows, making reference to your content block either using its ID or slug, using the following format:

[ls_content_block id="<ID>"]
[ls_content_block slug="<SLUG>"]

You can also use the “para” parameter, which gives you greater control over how the content is filtered. For example:

[ls_content_block id="<ID>" para="<PARA>"]
[ls_content_block slug="<SLUG>" para="<PARA>"]

See section below for full information regarding content processing and the PARA parameter.

The basic shortcode for each content block can be found on the main Content Blocks page. A more extensive list of the shortcodes can be found on the edit page for the specific block.

Shortcode Generator

The plugin provides a shortcode generator dialog box available from the WordPress TinyMCE editor window. To use it, place the cursor where you want the code to be inserted within the editor and click the Loomisoft logo.

The generator dialogue box allows you to select:

  • The required content block from those available
  • The desired content processing (See section below for full information regarding content processing and the PARA parameter)
  • Whether the ID or the slug should be used

Once you click “Insert”, the correct shortcode is inserted into the editor.

Placing Content Blocks Using Widgets

For within sidebars and widgetised areas, the plugin provides a widget that lets you place content blocks. Available from your WordPress site’s widget management page under menu item Appearance > Widgets, the widget can be dragged and dropped in the normal way.

Once inserted into the correct area, the widget allows you to select:

  • The required content block from those available
  • The desired content processing (See section below for full information regarding content processing and the PARA parameter)
  • Whether the ID or the slug should be used

Once you have made the relevant selections, click “Save”.

Placing Content Blocks Using PHP

If you are a web developer (or comfortable using PHP) and there are inaccessible areas of the theme where you want to enable content that you or your clients can amend as and when they need, you can use the provided PHP functions to embed content blocks.

The basic function syntax is as follows, making reference to your content block either using the its ID or slug:

<? echo ls_content_block_by_id( <ID> ); ?>
<? echo ls_content_block_by_slug( '<SLUG>' ); ?>

You can also use the “para” parameter, which gives you greater control over how the content is filtered. For example:

<? echo ls_content_block_by_id( <ID>, '<PARA>' ); ?>
<? echo ls_content_block_by_slug( '<SLUG>', '<PARA>' ); ?>

See section below for full information regarding content processing and the PARA parameter.

An extensive list of the PHP code snippets for each content block can be found on the edit page for the specific block.

Content Processing & PARA Parameter

WordPress does a few things before the content from a page or post gets displayed on your site. For instance, it processes HTML paragraph (p) tags, it runs shortcodes and even sends the content to the theme and any plugins so they can do their thing to the content and include their bits.

The plugin gives you versatile control over these processes when a block is called from within a page or post … you can:

  • Include or suppress paragraph tags inside the content block when, for instance, you want the text in the content block to show up as part of an existing line in your page/post
  • Run or suppress shortcodes inside the content block
  • Or do full content processing, which is essential for the correct operation of the page builders

Within shortcodes or PHP calls, you can do this through the PARA parameter, possible values for which are:

  • None specified (default) – Do not insert paragraph tags, but run shortcodes within the content block. Please note that when shortcodes within a content block are run, they themselves may have paragraph tags within them
  • “no-shortcodes” – Do not insert paragraph tags and do not run shortcodes. Please note that mark-ups set in the WordPress WYSIWYG editor (e.g. bold, underline, colours, headings, etc.) will still be shown
  • “paragraphs” – Insert paragraph tags and run shortcodes
  • “paragraphs-no-shortcodes” – Insert paragraph tags, but do not run shortcodes
  • “full” – Perform full WordPress content filtering

Notes:

  • While full content filtering is necessary to allow compatibility with visual page builders, other plugins (e.g. author information blocks, social sharing buttons, etc.) that are designed to insert content into posts and pages during this content filtering process will also kick into effect. The result is that these insertions end up being repeated more than once on a page or post with content blocks in them. If full content filtering is absolutely essential, but you do not wish the third party plugin to insert additional content, you may be able to suppress this from within that plugin’s settings. For example, StarBox, which inserts author information into posts and pages, has the option to “Hide Author Box from custom posts types”
  • For backward compatibility the plugin interprets the old para=”yes” option (or true in PHP) as para=”full”

Custom Variables

The plugin allows you to define custom variables, which can then be displayed within content blocks.

Setting Variables

To set a variable, you need to include it in the calling shortcode (e.g. within your page or post) or in the calling PHP code.

The basic syntaxes in shortcodes are:

[ls_content_block id="<ID>" para="<PARA>" <VARIABLE 1 NAME>="<VARIABLE 1 VALUE>" <VARIABLE 2 NAME>="<VARIABLE 2 VALUE>"]
[ls_content_block slug="<SLUG>" para="<PARA>" <VARIABLE 1 NAME>="<VARIABLE 1 VALUE>" <VARIABLE 2 NAME>="<VARIABLE 2 VALUE>"]

With variables passed as an associative array, the basic syntaxes in PHP are:

<? echo ls_content_block_by_id( <ID>, '<PARA>', array( '<VARIABLE 1 NAME>' => '<VARIABLE 1 VALUE>', '<VARIABLE 2 NAME>' => '<VARIABLE 2 VALUE>' ) ); ?>
<? echo ls_content_block_by_slug( '<SLUG>', '<PARA>', array( '<VARIABLE 1 NAME>' => '<VARIABLE 1 VALUE>', '<VARIABLE 2 NAME>' => '<VARIABLE 2 VALUE>' ) ); ?>

Notes:

  • Variable names must be lowercase alphanumeric (a-z, 0-9) and must begin with “var” (e.g. “varpercentage”, “varcountry20”, etc.).
  • In these examples, we have shown 2 variables, but you may use one or more.
  • Variable values may not contain an inverted comma (“) as WordPress will confuse this with the variable value delimiter.

Displaying Variables

Once defined, a content block (or one down a chain) can display the value of a variable within its content by using the shortcode:

[ls_content_block getvar="<VARIABLE NAME>"]

Notes:

  • After being set, variable values persist until a page or post is fully rendered unless they are overwritten. As such, once set, they may be called at any point after – whether in a content block or the post itself.
  • To avoid variable values causing potential issues within the final HTML of the page, they are HTML escaped before being displayed.

Other Useful Shortcodes

The following useful shortcodes, which can be used within content blocks as well as other places such as pages/posts, are provided by the plugin:

Date & Time:

The current date/time in standard PHP date format strings (See http://php.net/manual/en/function.date.php):

[ls_content_block datetime="<DATE/TIME FORMAT>"]

For example, the current date in dd/mm/yyyy format would be:

[ls_content_block datetime="d/m/Y"]

Site Title:

The title of your WordPress site as set in WordPress administration area – Settings > General:

[ls_content_block info="site-title"]

Current Page/Post Title:

[ls_content_block info="page-title"]

Note that this is the raw title of the page/post and not the same as the title within the HTML title tag, which can be changed by SEO plugins.

Content Block Chains and Circular References

As content blocks are themselves custom post types, they can contain shortcodes for embedding other content blocks. As such, the plugin allows you to have a chain of content blocks. For instance, you might have:

Post or Page contains Content Block A, which contains Content Block B, which contains Content Block C, etc.

The plugin is designed to protect against circular references that would cause an infinite loop. For example, you might have:

Post or Page contains Content Block A, which contains Content Block B, which contains Content Block A

Or more complex scenarios:

Post or Page contains Content Block A, which contains Content Block B, which contains Content Block C, which contains Content Block A

In each case, the plugin is designed to drop the second loop.

Help & More

We have designed our plugin to be intuitive and easy for someone with a fair amount of WordPress experience. We have also tried to make this documentation as extensive as it needs to be without confusing things.

However, if you have any questions or need help, then help is at hand. Please feel free to contact us – either through the contact form on our website or through the WordPress.org support system.

Bugs & Clashes

We use our own plugins in-house so we generally know if there are any issues straight away, but it is our users who really put them through their paces and expose them to a wide variety of situations. So if you find bugs, or clashes with other plugins or your theme, then we definitely want to hear from you so we can fix the issue.

Your Suggestions

If you have any suggestions for improvements, do let us know. We are always interested in making our plugins better through enhancements that fit in with the core purpose of the particular plugin.

Rate this Plugin

If you like this plugin … or better still, if you love it … please take a moment to rate it on WordPress.org and let the world know.