=== Plugin Name === Reusable Content & Text Blocks by Loomisoft Contributors: Loomisoft Donate link: https://www.paypal.me/loomisoft Tags: content blocks, text blocks, reusable content, reuusable content widget, reusable text, reuusable text widget, WPBakery, Visual Composer, Fusion Builder, Beaver Builder, SiteOrigin Page Builder, page builder, pagebuilder Requires at least: 3.9 Tested up to: 4.8.1 Stable tag: 1.3.2 License: GPLv3 or later License URI: https://www.gnu.org/licenses/gpl.html This plugin allows users to define modular blocks of text/content and place them in pages, posts, sidebars, etc. via shortcodes, widgets or PHP. == Description == 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 content so you can use the same content in multiple pages, posts and other places. The second is to provide an easy way to add complex custom content within sidebars and widgets. The recent version 1.0.5 of the plugin was updated to support WPBakery's Visual Composer, Avada's Fusion Builder, Beaver Builder and SiteOrigin Page Builder. Version 1.1.0 was updated to give greater control over how content blocks are pre-processed before being added to the containing page or post by providing a number of options as regards the "para" parameter (see below). While full content filtering is necessary to allow comatibility 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. Version 1.2.0 was updated to provide a shortcode generator dialogue box for the WordPress TinyMCE WYSIWYG editor so that shortcodes can be added to posts and pages easily and quickly. This version features a variables function, allowing variables to be defined when content blocks are called, the values of which can be displayed via shortcode. = Features = * Uses WordPress custom post type and custom post management to define reusable content blocks * Allows the use of shortcodes, widgets and PHP to place content blocks into pages, posts, sidebars, widgetised areas or anywhere on your site * Provides greater control over the adding of paragraph tags, running of shortcodes or running complete content filtering * Provides a shortcode generator dialogue box so that shortcodes can be added to posts and pages easily and quickly * Provides a widget to place content blocks into sidebars and other widgetised areas * Supports WPBakery's Visual Composer, Avada's Fusion Builder, Beaver Builder and SiteOrigin Page Builder * Allows variables to be defined when content blocks are called, the values of which can be displayed via shortcode * Provides a number of other useful shortcodes to place dynamic text (e.g. date/time, site title, page title) into posts = Defining Content/Text 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. Once defined and published, they can be used in your posts, pages and other areas in your site. **Note:** Only content blocks that are "published" will be displayed when used within the site. Others (i.e. those marked as "pending review", "draft", "private", "password protected" or set for future publication) will not be displayed. = Shortcodes = Content blocks can be added to your pages, posts or anywhere in your site that accepts shortcodes by using the content block's post 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>*"] See section below for full options as regards this parameter. In addition, you can also define variables for use within content blocks. For example: > [ls_content_block id="*<ID>*" para="*<PARA>*" *<variable>*="*<VALUE>*"] **Note:** Variable names must be lowercase alphanumeric (a-z, 0-9) and must begin with the letters "var". You can define as many variables as needed: > [ls_content_block id="*<ID>*" para="*<PARA>*" *<variable1>*="*<VALUE1>*" *<variable2>*="*<VALUE2>*"] See section below for full information regarding how variables may be displayed. = Shortcode Generator = Shortcodes can be easily and quickly be added to posts and pages by using the shortcode generator dialogue box from the WordPress TinyMCE WYSIWYG editor. This can be accessed by clicking the Loomisoft icon on the editor. The dialogue box allows the relevant content block, along with the various parameters, to be selected and inserted into the post. = Widgets = A custom widget, the "Loomisoft Content Block" widget, is provided so you can easily add content blocks to your sidebars and other widgetised areas. This can be accessed through the normal WordPress admin area Appearance > Widgets. = Access via PHP = Content blocks can also be added to your customised theme pages via PHP using the following code: > <?php echo ls_content_block_by_id( *<ID>* ); ?> > <?php echo ls_content_block_by_slug( '*<SLUG>*' ); ?> Again, you can also use the second ("para") parameter, which (in the same way as the shortcodes above) gives you greater control over how the content is filtered. For example: > <?php echo ls_content_block_by_id( *<ID>*, '*<PARA>*' ); ?> See section below for full options as regards this parameter. In addition, you can also define variables in an associative key => value array for use within content blocks. For example: > <?php echo ls_content_block_by_id( *<ID>*, '*<PARA>*', array( '*<variable>*' => '*<VALUE>*' ) ); ?> Note: Variable names must be lowercase alphanumeric (a-z, 0-9) and must begin with the letters "var". You can define as many variables as needed: > <?php echo ls_content_block_by_id( *<ID>*, '*<PARA>*', array( '*<variable1>*' => '*<VALUE1>*', '*<variable2>*' => '*<VALUE2>*' ) ); ?> See section below for full information regarding how variables may be displayed. = Use with Visual Page Builders = This plugin supports: * WPBakery's Visual Composer * Avada's Fusion Builder * Beaver Builder * SiteOrigin Page Builder It can also possibly be used with other visual page builders. However, others have not been tested. To use content blocks with visual page builders, you will need to: * If relevant to the specific page builder, enable the "lscontentblock" or "Content Blocks" post type within its settings * For shortcodes, use the para="full" attribute as described below * For the widget, select "Full Content Filtering" from the "Content Filtering / Paragraph Tags" dropdown * In the case of PHP, set the second parameter to 'full' = The "para" Parameter = The "para" parameter can be used within the content block shortcodes or PHP calls to control how content blocks are pre-processed before being added to the containing page or post. The syntax for the shortcode is as follows: > [ls_content_block id="*<ID>*" para="*<PARA>*"] > [ls_content_block slug="*<SLUG>*" para="*<PARA>*"] And for PHP, the syntax is: > <?php echo ls_content_block_by_id( *<ID>*, '*<PARA>*' ); ?> > <?php echo ls_content_block_by_slug( '*<SLUG>*', '*<PARA>*' ); ?> **Note:** The widget has a dropdown that allows you to select the relevant option. Options for *<PARA>* 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 comatibility 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 compatability the plugin interprets the old para="yes" option (or true in PHP) as para="full". = Displaying Variables = As described above, variables may be defined when calling a content block. Once defined, a content block (or content blocks down a chain of content blocks) can display the contents of a variable within its content by using the shortcode: > [ls_content_block getvar="*<variable>*"] **Notes:** * Shortcodes must be allowed in content blocks that need to use this shortcode. * When variables are displayed within content, they are HTML-escaped. = Content Blocks Within Content Blocks = If needed, content blocks can be used within other content blocks via shortcodes as described above. However, the parent content block must be called with shortcodes allowed within the "para" parameter (see above). A safety feature has been written into the plugin to avoid circular references, which would cause an infinite loop. For example, if content block "A" is used in content block "B" and vice versa, the plugin will drop the second loop. This is true also of more complex scenarios such as content block "A" used in content block "B" used in content block "C" used in content block "A". = Other Useful Shortcodes = This plugin also provides the following useful shortcodes, which can be used within content blocks as well as other places such as pages/posts: **Date & time:** (Using the 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:** (As set in WordPress admin area - Settings > General) > [ls_content_block info="site-title"] **Title of current page/post:** (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) > [ls_content_block info="page-title"] == Installation == Residing in the plugins repository in WordPress.org, the plugin may be installed directly from your WordPress administration area under Plugins > Add New. Search for "loomisoft", install the plugin and activate it. In addition, the plugin may be downloaded from WordPress.org (https://wordpress.org/plugins/loomisoft-content-blocks/). Once downloaded to your computer: * **Either:** Upload Directly From WordPress - Upload the downloaded ZIP file through the WordPress administrative area under Plugins > Add New, then click "Upload Plugin", browse to the file and select it, then click "Install Now". Once installed, activate the plugin. * **Or:** Upload Via FTP or Similar - Upload the UNZIPPED plugin files to the '/wp-content/plugins/loomisoft-content-blocks' folder. Once uploaded (installed), activate the plugin from the Plugins screen. When installed and activated, you can click Content Blocks on the menu and start. Full usage information may be found in Content Blocks > Usage & About == Frequently Asked Questions == = Are content blocks easy to add and edit? = Yes. Content blocks are designed to be easy to manage by using the native WordPress post management functions so you will probably already be very familiar with the process. You can access the relevant pages by clicking "Content Blocks" on the WordPress admin menu. = Can content blocks be placed anywhere on a site = Content blocks can be placed within post/page content, within sidebars, and other areas via shortcode, via widgets and via PHP. = Can content blocks be used in other content blocks? = Yes. The normal shortcode can be used. = Can visual page builders be used to create content blocks? = This version supports WPBakery's Visual Composer, Avada's Fusion Builder, Beaver Builder and SiteOrigin Page Builder. To use content blocks with page builder content, you will need to: * If relevant to the specific page builder, enable the "lscontentblock" or "Content Blocks" post type within its settings * For shortcodes, use the para="full" attribute as described below * For the widget, select "Full Content Filtering" checkbox from the "Content Filtering / Paragraph Tags" dropdown * In the case of PHP, set the second parameter to 'full' In principle, other page builders may also work. However, they have not been tested. If you come across others we have missed, please let us know. == Screenshots == 1. List of "Content Blocks" custom post type 1. Edit screen for content block 1. Access details listed for Content Block 1. Widget for placing content block into sidebars, widget bars == Changelog == = 1.0.2 = * Launch version = 1.0.3 = * Added ls_content_block_by_id and ls_content_block_by_slug PHP functions = 1.0.4 = * Fatal error bugfix = 1.0.5 = * Updated to support visual page builders including WPBakery's Visual Composer, Avada's Fusion Builder, Beaver Builder and SiteOrigin Page Builder = 1.0.6 = * Bugfix with Beaver Builder integration = 1.0.7 = * Bugfix of broken code handling Visual Composer integration = 1.0.8 = * Bugfix with invocation of blocks by PHP * Addition of error trapping to ensure IDs are numeric = 1.1.0 = * Addition of greater options for the "para" parameter and how content is pre-processed before being rendered * General clean-up and improvements over code = 1.2.0 = * Addition of shortcode generator dialogue box for TinyMCE editor * Major restructure of code and content block classes = 1.2.1 = * Minor amend to text translation function calls to fix PHP warning = 1.3.0 = * Addition of a variables function, allowing variables to be defined when content blocks are called, the values of which can be displayed via shortcode = 1.3.1 = * Bugfix with Usage & About page experienced by some users under certain PHP settings = 1.3.2 = * Amend to full content rendering when Visual Composer is present to ensure that VC custom styles for content blocks are included when blocks are added outside the main WordPress loop (e.g. in the header/footer). == Upgrade Notice == = 1.0.4 = Corrections and bugfixes = 1.0.5 = Updated to support visual page builders including WPBakery's Visual Composer, Avada's Fusion Builder, Beaver Builder and SiteOrigin Page Builder = 1.0.6 = Updated to fix issues with Beaver Builder integration = 1.0.7 = Corrected broken elements handling Visual Composer blocks = 1.0.8 = Corrected code relevant to invocation of blocks by PHP plus more stringent error trapping to ensure IDs are numeric = 1.1.0 = This version gives greater control over how content blocks are pre-processed before being rendered by providing a number of options with the "para" parameter to stop duplicate post insertions from other plugins (e.g. author information blocks or social sharing buttons plugins) = 1.2.0 = This version features an easy to use shortcode generator dialogue box so that shortcodes can be added directly into the WordPress WYSIWYG post editor. In addition, there have been major improvements to back-end code and code structure = 1.2.1 = Minor amend to text translation function calls to fix PHP warning = 1.3.0 = Addition of a variables function, allowing variables to be defined when content blocks are called, the values of which can be displayed via shortcode = 1.3.1 = Bugfix with Usage & About page experienced by some users under certain PHP settings = 1.3.2 = Amend to full content rendering when Visual Composer is present to ensure that VC custom styles for content blocks are included when blocks are added outside the main WordPress loop (e.g. in the header/footer).