post-snippets / classes / help.php

help.php in Post Snippets – Custom WordPress Code Snippets Customizer 1.9.1, at classes/help.php

258 lines 8.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Post Snippets Help.
4	*
5	* Class to handle the help texts and tabs on the settings screen.
6	*
7	* @package Post Snippets
8	* @author Johan Steen <artstorm at gmail dot com>
9	* @since Post Snippets 1.8.9
10	*/
11	class Post_Snippets_Help
12	{
13	/**
14	* Constructor.
15	*
16	* @since Post Snippets 1.8.9
17	* @param string The option page to load the help text on
18	*/
19	public function __construct( $option_page )
20	{
21	// If WordPress is 3.3 or higher, use the new Help API, otherwise call
22	// the old contextual help action.
23	global $wp_version;
24	if ( version_compare($wp_version, '3.3', '>=') ) {
25	add_action( 'load-' . $option_page, array(&$this,'add_help_tabs') );
26	} else {
27	add_action( 'contextual_help', array(&$this,'add_help'), 10, 3 );
28	}
29	}
30
31	/**
32	* Setup the help tabs and sidebar.
33	*
34	* @since Post Snippets 1.8.9
35	*/
36	public function add_help_tabs() {
37	$screen = get_current_screen();
38	$screen->set_help_sidebar( $this->help_sidebar() );
39	$screen->add_help_tab( array(
40	'id' => 'basic-plugin-help',
41	'title' => __( 'Basic', 'post-snippets' ),
42	'content' => $this->help_basic()
43	) );
44	$screen->add_help_tab( array(
45	'id' => 'shortcode-plugin-help',
46	'title' => __( 'Shortcode', 'post-snippets' ),
47	'content' => $this->help_shortcode()
48	) );
49	$screen->add_help_tab( array(
50	'id' => 'php-plugin-help',
51	'title' => __( 'PHP', 'post-snippets' ),
52	'content' => $this->help_php()
53	) );
54	$screen->add_help_tab( array(
55	'id' => 'advanced-plugin-help',
56	'title' => __( 'Advanced', 'post-snippets' ),
57	'content' => $this->help_advanced()
58	) );
59	}
60
61	/**
62	* The right sidebar help text.
63	*
64	* @since Post Snippets 1.8.9
65	* @return string The help text
66	*/
67	public function help_sidebar()
68	{
69	return '<p><strong>'.
70	__( 'For more information:', 'post-snippets' ).
71	'</strong></p>
72
73	<p><a href="http://wpstorm.net/wordpress-plugins/post-snippets/" target="_blank">'.
74	__( 'Post Snippets Documentation', 'post-snippets' ).
75	'</a></p>
76
77	<p><a href="http://wordpress.org/tags/post-snippets?forum_id=10" target="_blank">'.
78	__( 'Support Forums', 'post-snippets' ).
79	'</a></p>';
80	}
81
82	/**
83	* The basic help tab.
84	*
85	* @since Post Snippets 1.9.1
86	* @return string The help text
87	*/
88	public function help_basic()
89	{
90	return '<h2>'.
91	__( 'Title', 'post-snippets' ).
92	'</h2>
93	<p>'.
94	__( 'Give the snippet a title that helps you identify it in the post editor. This also becomes the name of the shortcode if you enable that option', 'post-snippets' ).
95	'</p>
96
97	<h2>'.
98	__( 'Variables', 'post-snippets' ).
99	'</h2>
100	<p>'.
101	__( 'A comma separated list of custom variables you can reference in your snippet.', 'post-snippets' ).
102	'</p>
103	<p><strong>'.
104	__( 'Example', 'post-snippets' ).
105	'</strong><br/>
106	<code>url,name</code></p>'.
107
108	'<h2>'.
109	__( 'Snippet', 'post-snippets' ).
110	'</h2>
111	<p>'.
112	__('This is the block of text, HTML or PHP to insert in the post or as a shortcode. If you have entered predefined variables you can reference them from the snippet by enclosing them in {} brackets.', 'post-snippets' ).
113	'</p>
114	<p><strong>'.
115	__( 'Example', 'post-snippets' ).
116	'</strong><br/>'.
117	__( 'To reference the variables in the example above, you would enter {url} and {name}. So if you enter this snippet:', 'post-snippets' ).
118	'<br/>
119	<code>This is the website of <a href="{url}">{name}</a></code>
120	<br/>'.
121	__( 'You will get the option to replace url and name on insert if they are defined as variables.', 'post-snippets').
122	'</p>
123
124	<h2>'
125	. __( 'Description', 'post-snippets' ).
126	'</h2>
127	<p>'.
128	__( 'An optional description for the Snippet. If filled out, the description will be displayed in the snippets insert window in the post editor.', 'post-snippets').
129	'</p>';
130	}
131
132	/**
133	* The shortcode help tab.
134	*
135	* @since Post Snippets 1.9.1
136	* @return string The help text
137	*/
138	public function help_shortcode()
139	{
140	return '<p>'.
141	__( 'When enabling the shortcode checkbox, the snippet is no longer inserted directly but instead inserted as a shortcode. The obvious advantage of this is of course that you can insert a block of text or code in many places on the site, and update the content from one single place.', 'post-snippets' ).
142	'</p>
143
144	<p>'.
145	__( 'The name to use the shortcode is the same as the title of the snippet (spaces are not allowed). When inserting a shortcode snippet, the shortcode and not the content will be inserted in the post.', 'post-snippets' ).
146	'</p>
147	<p>'.
148	__( 'If you enclose the shortcode in your posts, you can access the enclosed content by using the variable {content} in your snippet. The {content} variable is reserved, so don\'t use it in the variables field.', 'post-snippets' ).
149	'</p>';
150	}
151
152	/**
153	* The PHP help tab.
154	*
155	* @since Post Snippets 1.9.1
156	* @return string The help text
157	*/
158	public function help_php()
159	{
160	return '<p>'.
161	__('Snippets defined as shortcodes can optionally also be evaluated as PHP Code by enabling the PHP checkbox. PHP snippets is only available when treating the snippet as a shortcode.', 'post-snippets' ).
162	'</p>
163	<p><strong>'.
164	__( 'Example PHP Snippet', 'post-snippets' ).
165	'</strong><br/>
166	<code>
167	for ($i=1; $i<5; $i++) {<br/>
168	echo "{loop_me}<br/>";<br/>
169	};
170	</code></p>
171
172	<p>'.
173	__( 'With a snippet defined like the one above, you can call it with its shortcode definition in a post. Let\'s pretend that the example snippet is named phpcode and have one variable defined loop_me, then it would be called like this from a post:' , 'post-snippets' ).
174	'</p>
175
176	<code>[phpcode loop_me="post snippet with PHP!"]</code>
177
178	<p>'.
179	__( 'When the shortcode is executed the loop_me variable will be replaced with the string supplied in the shortcode and then the PHP code will be evaluated. (Outputting the string five times in this case. Wow!)', 'post-snippets' ).
180	'</p>
181	<p>'.
182	__( 'Note the evaluation order, any snippet variables will be replaced before the snippet is evaluated as PHP code. Also note that a PHP snippet don\'t need to be wrapped in <?php #code; ?>.', 'post-snippets' ).
183	'</p>';
184	}
185
186	/**
187	* The advanced help tab.
188	*
189	* @since Post Snippets 1.9.1
190	* @return string The help text
191	*/
192	public function help_advanced()
193	{
194	return '<p>'.
195	__('You can retrieve a Post Snippet directly from PHP, in a theme for instance, by using the get_post_snippet() function.', 'post-snippets').
196	'</p>
197
198	<h2>'.
199	__('Usage', 'post-snippets').
200	'</h2>
201	<p>'.
202	'<code>
203	<?php $my_snippet = get_post_snippet( $snippet_name, $snippet_vars ); ?>
204	</code></p>
205
206	<h2>'.
207	__('Parameters', 'post-snippets').
208	'</h2>
209	<p>
210	<code>$snippet_name</code><br/>'.
211	__('(string) (required) The name of the snippet to retrieve.', 'post-snippets').
212
213	'<br/><br/><code>'.
214	'$snippet_vars
215	</code><br/>'.
216	__('(string) The variables to pass to the snippet, formatted as a query string.', 'post-snippets').
217	'</p>
218
219	<h2>'.
220	__('Example', 'post-snippets').
221	'</h2>
222	<p><code>
223	<?php<br/>
224	$my_snippet = get_post_snippet( \'internal-link\', \'title=Awesome&url=2011/02/awesome/\' );<br/>
225	echo $my_snippet;<br/>
226	?>
227	</code></p>';
228	}
229
230
231	// -------------------------------------------------------------------------
232	// For compability with WordPress before v3.3.
233	// -------------------------------------------------------------------------
234
235	/**
236	* Contextual Help for WP < v3.3.
237	*
238	* Combines the help tabs above into one long help text for the help tab
239	* when run on WordPress versions before v3.3.
240	*
241	* @since Post Snippets 1.7.1
242	* @return string The Contextual Help
243	*/
244	public function add_help($contextual_help, $screen_id, $screen) {
245	if ( $screen->id == 'settings_page_post-snippets/post-snippets' ) {
246	$contextual_help = '<h1>'.__( 'Basic', 'post-snippets' ).'</h1>';
247	$contextual_help .= $this->help_basic();
248	$contextual_help .= '<h1>'.__( 'Shortcode', 'post-snippets' ).'</h1>';
249	$contextual_help .= $this->help_shortcode();
250	$contextual_help .= '<h1>'.__( 'PHP', 'post-snippets' ).'</h1>';
251	$contextual_help .= $this->help_php();
252	$contextual_help .= '<h1>'.__( 'Advanced', 'post-snippets' ).'</h1>';
253	$contextual_help .= $this->help_advanced();
254	}
255	return $contextual_help;
256	}
257	}
258