Skip to content

Refresh contextual help #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GaryJones merged 1 commit into from
Mar 18, 2022
Merged

Refresh contextual help #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions acm.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,7 @@
}

.acm-ui-wrapper p {

}

#conditionals-help {
width: 600px;
}

tr:hover .row-actions {
Expand Down Expand Up @@ -174,4 +170,4 @@ tr:hover .row-actions {
.acm-global-options #provider-field label {
float: left;
width: 125px;
}
}
6 changes: 5 additions & 1 deletion ad-code-manager.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
namespace Automattic\AdCodeManager;

use Ad_Code_Manager;
use Automattic\AdCodeManager\UI\Contextual_Help;
use Automattic\AdCodeManager\UI\Plugin_Actions;

const AD_CODE_MANAGER_VERSION = '0.5';
Expand All @@ -35,8 +36,8 @@
require_once __DIR__ . '/src/class-acm-provider.php';
require_once __DIR__ . '/src/class-acm-wp-list-table.php';
require_once __DIR__ . '/src/class-acm-widget.php';
require_once __DIR__ . '/src/markdown.php';
require_once __DIR__ . '/src/class-ad-code-manager.php';
require_once __DIR__ . '/src/UI/class-contextual-help.php';
require_once __DIR__ . '/src/UI/class-plugin-actions.php';

add_action(
Expand All @@ -50,6 +51,9 @@ function () {
add_action(
'admin_init',
function () {
$contextual_help = new Contextual_Help();
$contextual_help->run();

$plugin_actions = new Plugin_Actions();
$plugin_actions->run();
}
Expand Down
135 changes: 135 additions & 0 deletions src/UI/class-contextual-help.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
<?php
/**
* Ad Code Manager contextual help class
*
* @package Automattic\AdCodeManager
* @since 0.6.0
*/

declare(strict_types=1);

namespace Automattic\AdCodeManager\UI;

use WP_Screen;

/**
* User Interface changes for the plugins actions.
*
* @since 0.6.0
*/
final class Contextual_Help {

/**
* Register action and filter hook callbacks.
*
* @return void
*/
public function run(): void {
add_action( 'current_screen', array( $this, 'render' ) );
}

/**
* Add contextual help to the Ad Code Manager admin pages.
*
* @since 0.6.0
*
* @param WP_Screen $screen Screen object.
* @return void
*/
public function render( WP_Screen $screen ): void {
if ( 'settings_page_ad-code-manager' !== $screen->id ) {
return;
}

ob_start();
?>
<p><?php esc_html_e( 'Ad Code Manager gives non-developers an interface in the WordPress admin for configuring your complex set of ad codes. Generally an "Ad Code" is a set of parameters you need to pass to an ad server, so it can serve the proper ad.', 'ad-code-manager' ); ?></p>
<p><?php echo wp_kses_post( __( 'Some code-level configuration may be necessary to display the ads. See the <a href="https://github.com/Automattic/ad-code-manager">GitHub repository</a> for developer information.', 'ad-code-manager' ) ); ?></p>
<?php
$overview = ob_get_clean();

ob_start();
?>
<p><?php esc_html_e( 'Choose the ad network you use, and you will see a set of required fields to fill in, such as IDs. You can also set conditionals for each ad tag, which restricts the contexts for when the adverts are displayed. Priorities work pretty much the same way they work in WordPress. Lower numbers correspond with higher priority.', 'ad-code-manager' ); ?></p>
<p><?php esc_html_e( 'Once you\'ve finished creating the ad codes, you can display them in your theme using:', 'ad-code-manager' ); ?></p>
<ul>
<li><?php echo wp_kses_post( __( 'a template tag in your theme: <code>&lt;?php do_action( \'acm_tag\', $tag_id ) ?></code>', 'ad-code-manager' ) ); ?></li>
<li><?php echo wp_kses_post( __( 'a shortcode: <code>[acm-tag id="tag_id"]</code>', 'ad-code-manager' ) ); ?></li>
<li><?php esc_html_e( 'or using a widget.', 'ad-code-manager' ); ?></li>
</ul>
<?php
$configuration = ob_get_clean();

ob_start();
?>
<p><?php esc_html_e( 'In the fields below, you can choose which conditionals you want. Some can take a value (i.e. define a specific category) in the second field.', 'ad-code-manager' ); ?></p>
<p><?php esc_html_e( 'Here\'s an overview of the conditionals - they work the same as the functions of the same name in WordPress.', 'ad-code-manager' ); ?></p>
<dl>
<dt><a href="https://developer.wordpress.org/reference/functions/is_home/">is_home</a></dt>
<dd><?php echo wp_kses_post( __( 'When the main blog page is being displayed. This is the page which shows the time based blog content of your site, so if you\'ve set a static Page for the Front Page (see below), then this will only be true on the Page which you set as the "Posts page" in <i>Settings &gt; Reading</i>.', 'ad-code-manager' ) ); ?></dd>

<dt><a href="https://developer.wordpress.org/reference/functions/is_front_page">is_front_page</a></dt>
<dd><?php echo wp_kses_post( __( 'When the front of the site is displayed, whether it is posts or a Page. Returns true when the main blog page is being displayed and the <i>Settings &gt; Reading &gt; Front page displays</i> is set to "Your latest posts", <b>or</b> when <i>Settings</a> &gt; Reading &gt; Front page displays</i> is set to "A static page" and the "Front Page" value is the current Page being displayed.', 'ad-code-manager' ) ); ?></dd>

<dt><a href="https://developer.wordpress.org/reference/functions/is_category">is_category</a></dt>
<dd><?php esc_html_e( 'When any Category archive page is being displayed.', 'ad-code-manager' ); ?></dd>

<dt>is_category: 9</dt>
<dd><?php esc_html_e( 'When the archive page for Category 9 is being displayed.', 'ad-code-manager' ); ?></dd>

<dt>is_category: <?php esc_html_e( 'Stinky Cheeses', 'ad-code-manager' ); ?></dt>
<dd><?php esc_html_e( 'When the archive page for the Category with Name "Stinky Cheeses" is being displayed.', 'ad-code-manager' ); ?></dd>

<dt>is_category: <?php esc_html_e( 'blue-cheese', 'ad-code-manager' ); ?></dt>
<dd><?php esc_html_e( 'When the archive page for the Category with Category Slug "blue-cheese" is being displayed.', 'ad-code-manager' ); ?></dd>

<dt>is_category: <?php esc_html_e( 'array( 9, \'blue-cheese\', \'Stinky Cheeses\' )', 'ad-code-manager' ); ?></dt>
<dd><?php echo wp_kses_post( __( 'Returns true when the category of posts being displayed is either term_ID 9, or <i>slug</i> "blue-cheese", or <i>name</i> "Stinky Cheeses".', 'ad-code-manager' ) ); ?></dd>

<dt><a href="https://developer.wordpress.org/reference/functions/in_category/">in_category</a>: 5</dt>
<dd><?php esc_html_e( 'Returns true if the current post is <b>in</b> the specified category id.', 'ad-code-manager' ); ?></dd>

<dt><a href="https://developer.wordpress.org/reference/functions/is_tag">is_tag</a></dt>
<dd><?php esc_html_e( 'When any Tag archive page is being displayed.', 'ad-code-manager' ); ?></dd>

<dt>is_tag: mild</dt>
<dd><?php esc_html_e( 'When the archive page for tag with the slug of "mild" is being displayed.', 'ad-code-manager' ); ?></dd>

<dt>is_tag: array( 'sharp', 'mild', 'extreme' )</dt>
<dd><?php esc_html_e( 'Returns true when the tag archive being displayed has a slug of either "sharp", "mild", or "extreme".', 'ad-code-manager' ); ?></dd>

<dt>has_tag</dt>
<dd><?php esc_html_e( 'When the current post has a tag. Must be used inside The Loop.', 'ad-code-manager' ); ?></dd>

<dt>has_tag: mild</dt>
<dd><?php esc_html_e( 'When the current post has the tag "mild".', 'ad-code-manager' ); ?></dd>

<dt>has_tag: array( 'sharp', 'mild', 'extreme' )</dt>
<dd><?php esc_html_e( 'When the current post has any of the tags in the array.', 'ad-code-manager' ); ?></dd>
</dl>
<?php
$conditionals = ob_get_clean();

get_current_screen()->add_help_tab(
array(
'id' => 'acm-overview',
'title' => __( 'Overview', 'ad-code-manager' ),
'content' => $overview,
)
);
get_current_screen()->add_help_tab(
array(
'id' => 'acm-config',
'title' => __( 'Configuration', 'ad-code-manager' ),
'content' => $configuration,
)
);
get_current_screen()->add_help_tab(
array(
'id' => 'acm-conditionals',
'title' => 'Conditionals',
'content' => $conditionals,
)
);
}
}
82 changes: 0 additions & 82 deletions src/class-ad-code-manager.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,6 @@ function run() {
add_action( 'admin_enqueue_scripts', array( $this, 'register_scripts_and_styles' ) );
add_action( 'wp_ajax_acm_admin_action', array( $this, 'handle_admin_action' ) );

add_action( 'current_screen', array( $this, 'contextual_help' ) );
add_action( 'widgets_init', array( $this, 'register_widget' ) );
add_shortcode( 'acm-tag', array( $this, 'shortcode' ) );
// Workaround for PHP 5.4 warning: Creating default object from empty value in
Expand Down Expand Up @@ -621,87 +620,6 @@ function admin_view_controller() {
require_once dirname( AD_CODE_MANAGER_FILE ) . '/views/ad-code-manager.tpl.php';
}

function parse_readme_into_contextual_help() {
ob_start();
include_once dirname( AD_CODE_MANAGER_FILE ) . '/readme.txt';
$readme = ob_get_clean();
$sections = preg_split( '/==(.*)==/', $readme );
// Something's wrong with readme, fail silently
if ( 5 > count( $sections ) ) {
return;
}

$useful = array( $sections[2], $sections[4], $sections[7] );
foreach ( $useful as $i => $tab ) {
// Because WP.ORG Markdown has a different flavor
$useful[ $i ] = Markdown( str_replace( array( '= ', ' =' ), '**', $tab ) );
}
return $useful;
}

function contextual_help() {
global $pagenow;
if ( 'options-general.php' !== $pagenow || ! isset( $_GET['page'] ) || $_GET['page'] !== $this->plugin_slug ) {
return;
}
[ $description, $configuration, $filters ] = $this->parse_readme_into_contextual_help();
ob_start();
?>
<div id="conditionals-help">
<p><strong>Note:</strong> this is not full list of conditional tags, you can always check out <a href="http://codex.wordpress.org/Conditional_Tags" class="external text">Codex page</a>.</p>

<dl><dt> <tt><a href="http://codex.wordpress.org/Function_Reference/is_home" class="external text" title="http://codex.wordpress.org/Function_Reference/is_home">is_home()</a></tt>&nbsp;</dt><dd> When the main blog page is being displayed. This is the page which shows the time based blog content of your site, so if you've set a static Page for the Front Page (see below), then this will only be true on the Page which you set as the "Posts page" in <a href="http://codex.wordpress.org/Administration_Panels" title="Administration Panels" class="mw-redirect">Administration</a> &gt; <a href="http://codex.wordpress.org/Administration_Panels#Reading" title="Administration Panels" class="mw-redirect">Settings</a> &gt; <a href="http://codex.wordpress.org/Settings_Reading_SubPanel" title="Settings Reading SubPanel" class="mw-redirect">Reading</a>.
</dd></dl>
<dl><dt> <tt><a href="http://codex.wordpress.org/Function_Reference/is_front_page" class="external text" title="http://codex.wordpress.org/Function_Reference/is_front_page">is_front_page()</a></tt>&nbsp;</dt><dd> When the front of the site is displayed, whether it is posts or a <a href="http://codex.wordpress.org/Pages" title="Pages">Page</a>. Returns true when the main blog page is being displayed and the '<a href="http://codex.wordpress.org/Administration_Panels#Reading" title="Administration Panels" class="mw-redirect">Settings</a> &gt; <a href="http://codex.wordpress.org/Settings_Reading_SubPanel" title="Settings Reading SubPanel" class="mw-redirect">Reading</a> -&gt;Front page displays' is set to "Your latest posts", <b>or</b> when '<a href="http://codex.wordpress.org/Administration_Panels#Reading" title="Administration Panels" class="mw-redirect">Settings</a> &gt; <a href="http://codex.wordpress.org/Settings_Reading_SubPanel" title="Settings Reading SubPanel" class="mw-redirect">Reading</a> -&gt;Front page displays' is set to "A static page" and the "Front Page" value is the current <a href="/Pages" title="Pages">Page</a> being displayed.
</dd></dl>
<dl><dt> <tt><a href="http://codex.wordpress.org/Function_Reference/is_category" class="external text" title="http://codex.wordpress.org/Function_Reference/is_category">is_category()</a></tt>&nbsp;</dt><dd> When any Category archive page is being displayed.
</dd><dt> <tt>is_category( '9' )</tt>&nbsp;</dt><dd> When the archive page for Category 9 is being displayed.
</dd><dt> <tt>is_category( 'Stinky Cheeses' )</tt>&nbsp;</dt><dd> When the archive page for the Category with Name "Stinky Cheeses" is being displayed.
</dd><dt> <tt>is_category( 'blue-cheese' )</tt>&nbsp;</dt><dd> When the archive page for the Category with Category Slug "blue-cheese" is being displayed.
</dd><dt> <tt>is_category( array( 9, 'blue-cheese', 'Stinky Cheeses' ) )</tt>&nbsp;</dt><dd> Returns true when the category of posts being displayed is either term_ID 9, or <i>slug</i> "blue-cheese", or <i>name</i> "Stinky Cheeses".
</dd><dt> <tt>in_category( '5' )</tt>&nbsp;</dt><dd> Returns true if the current post is <b>in</b> the specified category id. <a href="http://codex.wordpress.org/Template_Tags/in_category" class="external text" title="http://codex.wordpress.org/Template_Tags/in_category">read more</a>
</dd></dl>
<dl><dt> <tt><a href="http://codex.wordpress.org/Function_Reference/is_tag" class="external text" title="http://codex.wordpress.org/Function_Reference/is_tag">is_tag()</a></tt>&nbsp;</dt><dd> When any Tag archive page is being displayed.
</dd><dt> <tt>is_tag( 'mild' )</tt>&nbsp;</dt><dd> When the archive page for tag with the slug of 'mild' is being displayed.
</dd><dt> <tt>is_tag( array( 'sharp', 'mild', 'extreme' ) )</tt>&nbsp;</dt><dd> Returns true when the tag archive being displayed has a slug of either "sharp", "mild", or "extreme".
</dd><dt> <tt>has_tag()</tt>&nbsp;</dt><dd> When the current post has a tag. Must be used inside The Loop.
</dd><dt> <tt>has_tag( 'mild' )</tt>&nbsp;</dt><dd> When the current post has the tag 'mild'.
</dd><dt> <tt>has_tag( array( 'sharp', 'mild', 'extreme' ) )</tt>&nbsp;</dt><dd> When the current post has any of the tags in the array.
</dd></dl>
</div>
<?php
$contextual_help = ob_get_clean();

get_current_screen()->add_help_tab(
array(
'id' => 'acm-overview',
'title' => 'Overview',
'content' => $description,
)
);
get_current_screen()->add_help_tab(
array(
'id' => 'acm-config',
'title' => 'Configuration',
'content' => $configuration,
)
);
get_current_screen()->add_help_tab(
array(
'id' => 'acm-filters',
'title' => 'Configuration Filters',
'content' => $filters,
)
);
get_current_screen()->add_help_tab(
array(
'id' => 'acm-conditionals',
'title' => 'Conditionals',
'content' => $contextual_help,
)
);
}

/**
* Register a custom widget to display ad zones
*/
Expand Down
Loading