Simple:Press Documentation

Plugin: Print Topic

Plugin Description

Plugin: Print Topic – This Simple:Press plugin allows for printing a hard copy of a complete topic or a single post and features a template file so the user can control what data is printed.

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Print Topic” section in the “Available Plugins – Install Simple:Press Plugins” panel under the forum Admin menu path Forum > Plugins > Available Plugins. From this panel the Simple:Press “Print Topic” plugin can be activated, or deleted by the admin.
  • When properly installed, a new folder in the “forum-plugin” folder named “print-topic” containing the “Print Topic” plugin files.

Activating this plugin provides:

  • A change to the new “Print Topic” section in the “Available Plugins – Install Simple:Press Plugins” panel under the Admin menu path Forum > Plugins > Available Plugins so the Simple:Press “Print Topic” plugin can be deactivated or uninstalled.
    • There are no ‘Options’ to be set up with this plugin.
    • The “Getting Started” link associated with the “Deactivate/Uninstall” selections should be selected to view the pertinent information regarding the plugin.
  • In the Topic View:
    • a new ‘Print’ button (printer icon) added to the topic header which if selected initiates the new Print Topic process for all the posts in the topic or a page of posts if the topic is displayed in the forum on multiple pages.
    • a modified ‘Print’ button (printer icon) in each post header within the topic which if selected initiates the new Print Topic process for that post instead of the previous simple print process.
  • A new “Print Topic” popup for the user to specify specifics regarding how the topic printing is accomplished.
    • Selections for printing all the posts in a topic or a page of posts in the topic (if the topic posts in the forum are displayed on multiple pages).
    • Selections for Image Printing to either “Print images as thumbnails” or “Enlarge images to available width.
    • A selection for Print Size with “Print font size as percentage” with variable percentage for 50 to 100.
    • A selection to “Open this topic in print preview”.
      • A new “Topic” print preview template identifying the Forum, the Topic Name, and showing the posts in the topic as they will be printed.
  • A new “Print Post” popup for the user to specify specifics regarding how the single post printing is accomplished.
    • A selection for Image Printing either “Print images as thumbnails” or “Enlarge images to available width.
    • A selection for Print Size with “Print font size as percentage” with variable percentage for 50 to 100.
    • A selection to “Open this post in print preview”.
      • A new “Post” print preview template identifying the Forum, the Topic Name, and showing the selected post from the topic as it will be printed.

There are no new permissions added to the permission sets due to this plugin.

Plugin Requirements

Simple:Press version 5.5.7 and above is required.

The Simple:Press plugin must be installed and activated before it is operational.

  • As part of the installation, a “Print Topic” section is added to the “Available Plugins – Install Simple:Press Plugins” panel under the admin menu Forum > Plugins > Available Plugins. From this panel the “Print Topic” plugin can be activated, deactivated, uninstalled, or deleted using its “Activate/Delete” and “Deactivate/Uninstall” selections.
  • There is no “Options” link because there are no options to be set up.

There are no new permissions added to the permission sets due to this plugin.

The plugin has four (4) template tag which are incorporated into supplied Simple:Press themes or into the plugin print template.

  • If the locations of the template tags in the themes/print template as well as the argument and parameter values for the template tags are acceptable, nothing need be done.
  • If any items relating to the plugin’s template tags called on theme pages is to be modified, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin.
  • In all cases any of this plugin’s template tags called on theme pages should be called conditionally, if (function_exists(‘ ‘)) so that if the “Print Topic” plugin is deactivated or does not exist, the website will continue to operate.

This plugin expects the printing capability already exists for the user attempting to print a topic or post.

Plugin Installation and Activation

Please see Using Plugins on how to obtain and install the Simple:Press “Print Topic” plugin.

  • Whatever method is used to add the Simple:Press plugin, the folder that should have been added to the forum plugin folder is named “print-topic“.
  • If using the “Simple:Press Upload Plugin – Upload a Simple:Press Plugin” panel at the forum Admin menu Forum > Plugins > Plugin Uploader, the folder to browse for after downloading it from the Simple:Press site is “print-topic.zip” before clicking the “Upload Now” button.

As mentioned there the default location for Simple:Press plugin folders is …/wp-content/sp-resources/forum-plugins. If this path is changed, it is important to note that the plugin’s folder and its content need to reside in the forum plugins folder wherever it has been moved and however it has been renamed. See Storage Locations for more information.

Activation is accomplished from the Admin Dashboard panel menu by selecting Forum > Plugins > Available Plugins from the drop down forum Admin menu. On the “Available Plugins – Install Simple:Press Plugins” panel select the “Print Topic” plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall” with a “Get Started” Link.

  • The “Getting Started” link associated with the “Deactivate/Uninstall” selections should be selected to view the pertinent information regarding the plugin.

To deactivate the plugin, click on “Deactivate”. The “Deactivate/Uninstall” label changes to “Activate/Delete”.

Plugin Administrative Options

There are no Administrative Options to set up with this plugin.

To be complete, the language translation files for this plugin, “Print Topic” should be installed or downloaded/properly placed in the appropriate forum-language folder for SP plugins using one of the procedures below in the “Plugin Language Translation” section of this page.

Plugin Language Translation

A plugin may not have language translation files, but in general each Simple:Press plugin has its own language translation files each with multiple pages for translating the forum plugin’s message strings.

Forum Plugin translation files are to reside in a unique forum folder location as defined by the “Simple:Press Plugin Language Files” entry on the “Integration – Storage Locations” forum Admin panel available through the forum Admin menu at Forum > Integration > Storage Locations.

  • The default location for forum plugin translation files is the folder “…/wp-content/sp-resources/forum-language/sp-plugins”.

Information regarding downloading language files, “mo’ language file placement, and translation (language localization) is found at Localization.

WARNING: On the Localization page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.

More information is available regarding translation files at Simple:Press Translations. which is the repository for Simple:Press language translation files. On the base page, select the “Getting Started Guide” link for basics about it’s use. On that page, select the “register a username here” link to obtain a password to the site. Use the “Contact Form” link to request the desired language if it is not currently available. The “Contact Form” link may also be used to volunteer to be a validator for a translation project.

The “Print Topic” plugin’s available language translation files with translation statistics, and message translations can be viewed at Print Topic within the repository for Simple:Press language translation files.

  • Installing the Simple:Press “Print Topic” Plugin Language Translation “.mo” files
    The “Print Topic” plugin language translations files for each language can be correctly located in two ways.

    • Using the Admin Word:Press “Site Language” and Simple:Press “Language Translation” Features
      WARNING: On the Localization codex page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.
        • Under the “Language Translation Selection Sequences” heading, the “Coordinated Language Translation File Download Using the Simple:Press ‘Language Translation’ Selection” section, follow the instructions at “Adding its Translation File(s) After Downloading/Activating a Simple:Press Theme or Simple:Press Plugin”.
          • Follow the instructions to select the “Site Language” and then get to the admin page with the “Integration – Language Translations” section where this plugin should have an entry.
          • Click on the “Install” button for this plugin, “Print Topic” to install the language translation file for the current “Site Language” language.
          • Be sure to verify the locale (filename) for the “.mo” file matches the language code for the language as referenced in the “Warning” above. If it does not, change it to match.
          • As called out in the section, continue to change the “Site Language” language and repeat the process until all desired “Print Topic” plugin translation files have been installed.

       

    • Manually Finding and Storing the Simple:Press “Print Topic” Plugin Language Translation ‘mo’ files
    • WARNING: On the Localization codex page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.
    • After reviewing the material discussed under the “Language Translation Selection Sequences” heading, the “Manual Installation of Simple:Press Language Translation Files section, follow the steps outlined at “Finding and Storing ANY Simple:Press Plugin’s Language Translation ‘mo’ files”.
    • Each time through the process at the step, “Scroll down the list and click on the name of the plugin whose language files are being sought to see the translation file Version Number available”, substitute “Print-Topic” for the phrase “the name of the plugin whose language files are being sought”.
    • Be sure to verify the locale (filename) for the “.mo” file matches the language code for the language as referenced in the “Warning” above. If it does not, change it to match.
    • Repeat the steps for each language it is desired to have a translation file (french, spanish, etc.) for the plugin on the website.

Plugin Usage

Forum Users and Admins can print a complete topic with all its posts (or a page of posts if the topic is displayed on multiple pages) or a single post in a topic.

    • Printing a complete Topic
    • Display the topic by going to the Topic View for the topic to be printed.
    • In the topic view below the page header is a topic header followed by the topic posts (possibly on multiple pages).
    • In the topic header, find and click on the print button (the default is a printer icon that when hovering the cursor over the icon displays the message “Topic Print Options”) to have the “Print Options”, “Print Topic” popup displayed.
    • In the “Print Options”, “Print Topic” popup:
      • “Printing Scope” Options
      • If the topic posts are displayed on a single page, the “Print Scope” printing options are not displayed.
        • Proceed to the “Image Printing” options to print the entire topic.
      • If the topic posts are displayed on multiple pages, because the number of posts in the topic exceeds the value set by the forum Admin for “Topics to display per page:” in “Topic View Formatting” on the Options- General Display Settings panel accessed from the Admin menu at Forum > Options > General Display Settings, the “Print Scope” printing options are displayed.
        • Print all the posts in the topic regardless of the number of display pages by clicking the check box to the left of “Print entire topic”. A check box is selected when it contains a green check mark.
      • “Image Printing” Options
      • Print images as thumbnails by clicking the check box to the left of “Print images as thumbnails”. A check box is selected when it contains a green check mark.
      • Enlarge images to available width by clicking the check box to the left of “Enlarge images to available width”. A check box is selected when it contains a green check mark.
      • “Print Size” Options
      • Select the desired “Print Size” percentage by clicking in the box to the right of “Print font size as percentage” to see the up/down arrowheads to the right of the percentage number in the box.
        • Use the up/down arrowheads to adjust the number in the box to the desired percentage.
      • Click on the “OPEN THIS TOPIC IN PRINT VIEW” button to have the Topic with all its posts displayed as it will be printed with the Forum Name and Topic Name listed above the posts.
    • If the displayed page does not look as desired or it is desired to not print all the posts, click on the “Go Back to Topic” button above the Forum Name on the page to cancel the print operation and return to the topic view where
      • the print process could be restarted with different “Print Topic” options selected, or
      • a single post could be selected for printing.
    • If the displayed page is satisfactory, click on the “Print this Topic” button above the Forum Name on the page to have the Topic with all of posts printed.

 

    • Printing a page from a complete Topic

Note: This option is only possible if the topic posts are displayed on multiple pages because the number of posts in the topics exceeds the value set by the forum Admin for “Topics to display per page:” in “Topic View Formatting” on the Options- General Display Settings panel accessed from the Admin menu at Forum > Options > General Display Settings.Otherwise the process reverts to printing the entire post because the “Print Scope” options do not appear.

    • Display the topic by going to the Topic View for the topic to be printed.
    • Display the topic page to be printed with its posts.
    • In the topic view below the page header is a topic header followed by each of the topic posts.
    • In the topic header, find and click on the print button (the default is a printer icon that when hovering the cursor over the icon displays the message “Topic Print Options”) to have the “Print Options”, “Print Topic” popup displayed.
    • In the “Print Options”, “Print Topic” popup:
      • “Printing Scope” Options
      • Print only the posts on the displayed topic page by clicking the check box to the left of “Print this page only”. A check box is selected when it contains a green check mark.
      • “Image Printing” Options
      • Print images as thumbnails by clicking the check box to the left of “Print images as thumbnails”. A check box is selected when it contains a green check mark.
      • Enlarge images to available width by clicking the check box to the left of “Enlarge images to available width”. A check box is selected when it contains a green check mark.
      • “Print Size” Options
      • Select the desired “Print Size” percentage by clicking in the box to the right of “Print font size as percentage” to see the up/down arrowheads to the right of the percentage number in the box.
        • Use the up/down arrowheads to adjust the number in the box to the desired percentage.
      • Click on the “OPEN THIS TOPIC IN PRINT VIEW” button to have the topic page with its posts displayed as it will be printed with the Forum Name and Topic Name listed above the posts.
    • If the displayed page does not look as desired or it is decided to not print this topic page of posts, click on the “Go Back to Topic” button above the Forum Name on the page to cancel the print operation and return to the topic view where
      • the print process could be restarted with different “Print Topic” options selected, or
      • a single post could be selected for printing.
    • If the displayed page is satisfactory, click on the “Print this Topic” button above the Forum Name on the page to have the topic page with its posts printed.

 

  • Printing a Single Post in a Topic
  • Display the topic by going to the Topic View for the topic to be printed.
  • Display the post to be printed.
    • If the topic consists of multiple pages of posts, this may require hunting through the pages to find the post.
  • In the topic view each post in the topic has a header.
  • In the post header of the post to be printed, find and click on the print button (the default is a printer icon that when hovering the cursor over the icon displays the message “Print this post”) to have the “Print Options”, “Print Post” popup displayed.
  • In the “Print Options”, “Print Post” popup:
    • “Image Printing” Options
    • Print images as thumbnails by clicking the check box to the left of “Print images as thumbnails”. A check box is selected when it contains a green check mark.
    • Enlarge images to available width by clicking the check box to the left of “Enlarge images to available width”. A check box is selected when it contains a green check mark.
    • “Print Size” Options
    • Select the desired “Print Size” percentage by clicking in the box to the right of “Print font size as percentage” to see the up/down arrowheads to the right of the percentage number in the box.
      • Use the up/down arrowheads to adjust the number in the box to the desired percentage.
    • Click on the “OPEN THIS POST IN PRINT VIEW” button to have the Post displayed as it will be printed with the Forum Name and Topic Name listed above the post.
  • If the displayed page does not look as desired or it is decided to not print this post, click on the “Go Back to Topic” button above the Forum Name on the page to cancel the print operation and return to the topic view where
    • the print process could be restarted with a different post and/or different “Print Post” options selected, or
    • the entire Topic or a page of topic posts could be selected for printing.
  • If the displayed page is satisfactory, click on the “Print this Post” button above the Forum Name on the page to have the post printed.

Plugin Special Notes

This plugin expects the printing capability already exists for the user attempting to print a topic or post.

 

Template Tags Used in the Plugin

There are four (4) template tags available for this plugin that allows further customization of the plugin’s usage or otherwise customize the website.

  • If the default locations in the themes/plugin’s print template as well as the arguments and parameter values for the template tags are acceptable, nothing need be done.
  • If any items relating to the plugin’s template tags called on theme pages is to be modified, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin.
  • In all cases any of this plugin’s template tags called on theme pages should be called conditionally, if (function_exists(‘ ‘)) so that if the “Print Topic” plugin is deactivated or does not exist, the website will continue to operate.

The Template Tags can be viewed by selecting their links below.

Action and Hooks Used in the Plugin

There are Actions and Hooks available in the Plugin’s Template Tags. The Template Tag’s Action and Hooks can be viewed by selecting its link below.

There are no other Actions and Hooks available for this plugin.

Plugin and Template Tag Changelog

Since Simple:Press version 5.5.5.

Codex page sync’d to code version 5.5.6 and plugin version 1.0.0.



Individual Template Tags


 

sp_PrintTopicView

Description

sp_PrintTopicView() – This template adds a view topic print button on topic views.

Usage

sp_PrintTopicView($args=”, $label=”, $toolTip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spPrintTopicView’
‘tagClass’ => ‘spButton’
‘icon’ => ‘sp_Print.png’
‘iconClass’ => ‘spIcon’
‘echo’ => 1

‘tagId’: CSS ID for the Div.
‘tagClass’: CSS Class for the Div.
‘icon’: Filename of the file to display for the icon.
‘iconClass’: CSS Class for the icon.
‘echo’: Flag to indicate whether to write out the generated html display code or just return the html display code. One (1) is true and causes the html display code to be written to the display. Zero (0) is false and causes the html display code to be returned instead of written out.

$label – Text to display on the Print Topic icon.
Type:
(string) (optional)
Default:
None

$toolTip – Text displayed when the cursor is hovered over the Print Topic icon.
Type:
(string) (optional)
Default:
None

Special Notes

In standard supplied Simple:Press themes this template tag is included in the topic view (‘spTopicView.php’) file, but only in the “Not Mobile” configuration of themes with both “Not Mobile” and “Mobile” configurations.
The exception is:

    • the reboot theme where the template tag is not included in the ‘spTopicView.php’ file, but is included only in the ‘spTopicViewDesktop.php’ files. It is not included in the ‘spTopicViewMobile.php’ file.

 

The function is called conditionally, if (function_exists(‘ ‘)), so that if the “Print Topic” plugin is deactivated or does not exist, the website will continue to operate.

The template tag can be placed elsewhere in the forum pages if that better fits the site’s theme. If the template tag is to be modified or its location on a page changed, it is suggested a Custom or Child theme be made to accept the modified template tag. Please see discussion at Template Tags Used in the Plugin.

This template tag function requires the usage of the ‘sp-print-tags.php’ file located in the plugin’s template-tag folder.

Examples

In the Simple:Press Default theme Topic View page conditionally display the Print Topic button with the ‘tagClass’ of “spLink spRight”, no label on the print topic button, and the message “Topic Print Options” displayed when the cursor is hovered over the Print Topic button. In the Default theme the following template tag is placed in the ‘spTopicView’ file:

if (function_exists('sp_PrintTopicView')) sp_PrintTopicView('tagClass=spLink spRight', '', __sp('Topic Print Options'));

 

Actions and Hooks Used in the sp_PrintTopicView Template Tag

  • apply_filters(‘sph_PrintTopicView_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_PrintTopicView’, $out, $a) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_PrintTopic

Description

sp_PrintTopic() – This template displays the Topic Print button on the actual print topic/print post template.

Usage

sp_PrintTopic($args=”, $label=”, $toolTip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spPrintTopic’
‘tagClass’ => ‘spButton’
‘icon’ => ‘sp_Print.png’
‘iconClass’ => ‘spIcon’
‘echo’ => 1

‘tagId’: CSS ID for the Div.
‘tagClass’: CSS Class for the Div.
‘icon’: Filename of the file to display for the icon.
‘iconClass’: CSS Class for the icon.
‘echo’: Flag to indicate whether to write out the generated html display code or just return the html display code. One (1) is true and causes the html display code to be written to the display. Zero (0) is false and causes the html display code to be returned instead of written out.

$label – Text to display on the Print Topic/Post icon.
Type:
(string) (optional)
Default:
None

$toolTip – Text displayed when the cursor is hovered over the Print Topic/Post icon.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag is included in the Print Topic plugin template (‘spTopicPrintView.php’) file.

This template tag function requires the usage of the ‘sp-print-tags.php’ file located in the plugin’s template-tag folder.

Examples

Display the print topic button with ‘tagClass’ of “spButton spLeft”, the label “Print this %s'” where the %s’ is replaced with the contents of $bLabel which will be “Topic” when printing the entire topic or “Post” when printing a single post from the topic, and no message when the cursor hovers over the icon..

sp_PrintTopic('tagClass=spButton spLeft', sprintf(__('Print this %s', 'sp-print'), $bLabel));

 

Actions and Hooks Used in the sp_PrintTopic Template Tag

  • apply_filters(‘sph_PrintTopic_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_PrintTopic’, $out, $a) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_GoBack

Description

sp_GoBack() – This template displays the ‘Go Back’ button on the print topic/post template.

Usage

sp_GoBack($args=”, $label=”, $toolTip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spGoBack’
‘tagClass’ => ‘spButton’
‘icon’ => ‘sp_ArrowLeft.png’
‘iconClass’ => ‘spIcon’
‘echo’ => 1

‘tagId’: CSS ID for the Div.
‘tagClass’: CSS Class for the Div.
‘icon’: Filename of the file to display for the icon.
‘iconClass’: CSS Class for the icon.
‘echo’: Flag to indicate whether to write out the generated html display code or just return the html display code. One (1) is true and causes the html display code to be written to the display. Zero (0) is false and causes the html display code to be returned instead of written out.

$label – Text to display on the ‘Go Back’ icon.
Type:
(string) (optional)
Default:
None

$toolTip – Text displayed when the cursor is hovered over the ‘Go Back’ icon.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag is included in the Print Topic plugin template (‘spTopicPrintView.php’) file.

This template tag function requires the usage of the ‘sp-print-tags.php’ file located in the plugin’s template-tag folder.

Examples

Display the “Go back” button with ‘tagClass’ of “spButton spLeft”, the label “Print this %s'” where the %s’ is replaced with the contents of $bLabel which will be “Topic” when printing the entire topic or “Post” when printing a single post from the topic, and no message when the cursor hovers over the icon.

sp_GoBack('tagClass=spButton spLeft', __('Go back to Topic', 'sp-print));

 

Actions and Hooks Used in the sp_GoBack Template Tag

  • apply_filters(‘sph_GoBack_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_GoBack’, $out, $a) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_print_topic_single_post_tag

Description

sp_print_topic_single_post_tag() – This template replaces the onclick in the standard print post tag.

Usage

sp_print_topic_single_post_tag($out, $a);

Arguments

  • None

Special Notes

Without the Print Topic plugin clicking on the ‘print’ button in the header of each post of a topic in Topic View results in a simple post preview and post print process.

When the Print Topic plugin is activated and the ‘print’ button in a post header is clicked, this template tag replaces the simple post preview and print process with the Print Topic process for the single post.

This is accomplished by using ‘add_filter’ to tie ‘sp_print_topic_single_post_tag’ to the apply_filter(‘sph_PostIndexPrint’. $out, $a) in the Topic View function sp_PostIndexPrint() contained in the ‘sp-topic-view-functions.php’ file.

This template tag function requires the usage of the ‘sp-print-tags.php’ file located in the plugin’s template-tag folder.

Examples

  • None

 

Actions and Hooks Used in the sp_print_topic_single_post_tag Template Tag

  • None of its own. It uses the actions and hooks in the ‘sp_PostIndexPrint’ function.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


More Topics In SimplePress: Plugins


Copyright © 2006-2019 Simple:Press. All Rights Reserved.