PluginProbe
Code Embed / trunk
Code Embed vtrunk
2.6.4 2.6.3 2.6.2 2.6.1 trunk 1.0 1.1 1.2 1.3 1.4.1 1.5.1 1.6.1 2.0.2 2.1.2 2.2.2 2.3.9 2.4 2.5.1 2.5.2 2.6
simple-embed-code / readme.txt

readme.txt in Code Embed trunk, at readme.txt

397 lines 25.0 KB
No matching file
Up and down to move Enter to open Esc to close
Raw Download Zip
1 === Code Embed ===
2 Contributors: dartiss
3 Donate link: https://artiss.blog/donate
4 Tags: code, embed, html, css, javascript
5 Requires at least: 4.9
6 Tested up to: 7.1
7 Requires PHP: 7.4
8 Stable tag: 2.6.4
9 License: GPLv2 or later
10 License URI: https://www.gnu.org/licenses/gpl-2.0.html
11
12 Code Embed provides a very easy and efficient way to embed code (JavaScript, CSS and HTML) in your posts and pages.
13
14 == Description ==
15
16 **IMPORTANT: If updating from an earlier version of the plugin, please check the section named "Plugin Behaviour Changes", below, for anything which could impact your existing set-up**
17
18 Code Embed allows you to embed code (JavaScript, CSS and HTML - it can't be used for server-side code, such as PHP) in a post, without the content being changed by the editor. This is incredibly useful for embedding third-party scripts, etc. The plugin is used by many large sites, including Mozilla.
19
20 Key features include...
21
22 * Add HTML or JavaScript to posts or pages - particularly useful for embedding videos!
23 * Embed in widgets using the [Widget Logic](https://wordpress.org/plugins/widget-logic/ "Widget Logic") plugin.
24 * Global embedding allows you to set up some code in one post or page and then access it from another.
25 * Modify the keywords or identifiers used for embedding the code to your own choice.
26 * Search for embedding code via a simple search option.
27 * Add a simple suffix to the embed code to convert videos to responsive output.
28 * Embed an external script directly using just the URL.
29 * Conforms to WCAG 2.1 AA standards.
30 * And much, much more!
31
32 Iconography is courtesy of the very talented [Janki Rathod](https://www.fiverr.com/jankirathore).
33
34 **Please visit the [Github page](https://github.com/dartiss/code-embed "Github") for the latest code development, planned enhancements and known issues.**
35
36 == Getting Started ==
37
38 To use this plugin, you need to have custom fields enabled on your site. If you're using the block editor, you may need to switch this on first - please scroll down to the next section to learn how to do this. If you're using the classic editor, then you'll find the custom fields at the bottom of the editor screen.
39
40 Although this plugin works for both posts and pages, for simplicity I will simply refer to posts - bear in mind that pages work in the same way.
41
42 Once you have custom fields switched on, here's how easy it is to use…
43
44 1. Once you have the plugin installed, start a new post.
45 2. Scroll down to the bottom of the screen and look for the "Custom Fields" section.
46 3. Under "Add New Custom Field", enter a name of `CODE1` and your embed code as the value.
47 4. In your post content, add `{{CODE1}}` where you wish the embed code to appear.
48
49 And that's it - when the post is viewed or previewed, `{{CODE1}}` will be replaced with the code that you asked to be embedded.
50
51 This should get you started - for more information and advanced options, please see below. Alternatively, there's a fantastic guide at [Elftronix](http://www.elftronix.com/free-easy-plugin-add-javascript-to-wordpress-posts-pages/ "Free Easy Plugin! Add Javascript to WordPress Posts & Pages") which I would recommend.
52
53 == Using this plugin with the block editor (aka Gutenberg) ==
54
55 By default, custom fields are hidden inside the block editor but can be revealed.
56
57 1. Edit or create a post.
58 2. Click the settings button (three dots) in the top right-hand corner.
59 3. Go to Preferences.
60 4. Click the Panels tab.
61 5. You will find a button to toggle the 'Custom Fields' meta box - make sure this is toggled to "on".
62 6. A button should appear titled "Enable & Reload" - you'll need to click on that and wait for the page to reload before the custom fields will appear.
63
64 Check out the screenshots for how the custom fields should look.
65
66 == I can't find the custom fields ==
67
68 For block editor users, I'm assuming you've done the above. For classic editor users, the custom fields should be present by default. In all cases they should appear at the bottom of the editor screen.
69
70 From version 2.4, anyone without the "unfiltered HTML" capability won't be able to use custom fields, for added security. Please see the section "Custom Field Security", below, for more details.
71
72 If none of the above applies, then you may have a theme or plugin that removes this or may have a problem with your WordPress installation - you will need to try the usual diagnostics to try and resolve this, including requesting help on [the WordPress support forum](https://wordpress.org/support/forum/how-to-and-troubleshooting/ "Fixing WordPress Forum").
73
74 == The Code Embed Options Screen ==
75
76 While in WP Admin, if you go to Settings -> Code Embed, you'll be able to access the options that are available for this plugin.
77
78 Code embedding is performed via a special keyword that you must use to uniquely identify where you wish the code to appear. This consists of an opening identifier (something that goes at the beginning), a keyword and then a closing identifier. You may also add a suffix to the end of the keyword if you wish to embed multiple pieces of code within the same post.
79
80 From this options screen, you can specify the above identifier that you wish to use. By default, the opening and closing identifiers are double braces and the keyword is `CODE`. During these instructions these will be used in all examples.
81
82 The options screen is only available to those with a capability to manage options or greater. All the other Code Embed menu options are available to users with a capability to edit posts or greater.
83
84 == How to Embed Code ==
85
86 To embed in a post, you need to find the meta box under the post named "Custom Fields". If this is missing, you may need to add it by clicking on the "Screen Options" tab at the top of the new post screen.
87
88 Now create a new custom field with the name of your keyword - e.g. `CODE`. The value of this field will be the code that you wish to embed. Save this custom field.
89
90 Now, wherever you wish the code to appear in your post, simply put the full identifier (opening, keyword and closing characters). For example, `{{CODE}}`.
91
92 If you wish to embed multiple pieces of code within a post, you can add a suffix to the keyword. So we may set up 2 custom fields named `CODE1` and `CODE2`. Then in our post we would specify either `{{CODE1}}` or `{{CODE2}}` depending on which you wish to display.
93
94 Don't forget - via the options screen you can change any part of this identifier to your own taste.
95
96 == How to Embed Code from an External URL ==
97
98 If you specify a URL within your post, surrounded by your choice of identifiers, then the contents of the URL will be embedded within your post.
99
100 Obviously, be careful when embedding a URL that you have no control over, as this may be used to hijack your post by injecting, for example, dangerous JavaScript.
101
102 For example, using the default options, you could embed the contents of a URL using the following method...
103
104 `{{http://www.example.com/code.php}}`
105
106 or
107
108 `{{https://www.example.com/code.html}}`
109
110 == How to Use Global Embedding ==
111
112 You can also create global embeds - that is, creating one piece of embed code and using it in multiple posts or pages.
113
114 To do this, simply make reference to an already defined (but unique) piece of embed code from another post or page.
115
116 So, let's say in one post you define a custom field named `CODE1`. You can, if you wish, place `{{CODE1}}` not just in that post but also in another and it will work.
117
118 However, bear in mind that the embed code name must be unique - you can't have defined it in multiple posts, otherwise the plugin won't know which one you're referring to (although it will report this and list the posts that it has been used in).
119
120 In the administration menu, there is a sidebar menu named "Tools". Under this is a sub-menu named "Code Search". Use this to search for specific embed names and it will list all the posts/pages that they're used on, along with the code for each.
121
122 == Embedding in Widgets ==
123
124 Natively, you cannot use the embed facilities within sidebar widgets. However, if you install the plugin [Widget Logic](http://wordpress.org/extend/plugins/widget-logic/ "Widget Logic"), then Code Embed has been set up to make use of this and add the ability.
125
126 * Install [Widget Logic](http://wordpress.org/extend/plugins/widget-logic/ "Widget Logic") and activate.
127 * In Administration, select the Widgets page from the Appearance menu. At the bottom there will be a set of Widget Logic options.
128 * Ensure 'Use widget_content filter' is ticked and press Save.
129
130 Although you cannot set up embed code within a widget, you can make reference to it, for example by writing `{{CODE1}}` in the widget.
131
132 == Responsive Output Conversion ==
133
134 Responsive output is where an element on a web page dynamically resizes depending upon the current available size. Most video embeds, for instance, will be a fixed size. This is fine if your website is also of a fixed size; however, if you have a responsive site then this is not suitable.
135
136 Code Embed provides a simple suffix that can be added to an embed code and will convert the output to being responsive. This works best with videos.
137
138 To use, when adding the embed code onto the page, simply add `_RES` to the end, before the final identifier. For example, `{{CODE1_RES}}`. The `_RES` should not be added to the custom fields definition.
139
140 This will now output the embedded code at full width, dynamically resizing as required.
141
142 If you don't wish the output to be full width, you can specify a maximum width by adding an additional `_x` on the end, where `x` is the required width in pixels. For example, `{{CODE1_RES_500}}` will output `CODE1` as responsive but with a maximum width of 500 pixels.
143
144 **It should be noted that this is an experimental addition and will not work in all circumstances.**
145
146 == Embedding in excerpts ==
147
148 By default, embed code will not appear in excerpts. However, you can switch this ability on via the Code Embed options screen. If you do this, then the standard rules of excerpts will still apply but only once the code embed has been applied. For example, excerpts are just text, a specific length, etc.
149
150 == Filtering of code ==
151
152 By default, WordPress allows unfiltered HTML to be used by users in post custom fields, even if their role is set up otherwise. This opens up the possibility of leaving a site vulnerable, if any plugins that use this data don't check it appropriately.
153
154 "Out of the box," neither the contributor nor author roles have unfiltered HTML capabilities but can access custom post fields.
155
156 As this plugin requires the use of unfiltered HTML, we need to ensure that only authorized users can use it. From version 2.5, any users without this permission that update a post containing embeds from this plugin will cause the code to be filtered.
157
158 == Plugin Behaviour Changes ==
159
160 Security hardening has meant that some changes to behaviour have had to change after specific releases. Here I'll document any known changes...
161
162 * Version 2.6.4 - A global `<script>` embed will now have scripts stripped on any post authored by a user without `unfiltered_html`. Safe-HTML global embeds (iframes, video, etc.) are unaffected. Previously scripts rendered everywhere.
163
164 * Version 2.6.4 - Global embeds stored on a draft/private post stop resolving on the front end. If you (or your users) deliberately keep a "global embed library" as an unpublished post, that pattern breaks - they'd need to publish it
165
166 * Version 2.6.3 - Global embeds are now case-sensitive (which it always should have been). If any existing live content relies on accidental case-insensitive matching (e.g. {{CODE1}} pulling a code1 field), it will stop resolving
167
168 == Reviews & Mentions ==
169
170 "Works like a dream. Fantastic!" - Anita.
171
172 "Thank you for this plugin. I tried numerous other iframe plugins and none of them would work for me! This plugin worked like a charm the FIRST time." - KerryAnn May.
173
174 [Embedding content](http://wsdblog.westbrook.k12.me.us/blog/2009/12/24/embedding-content/ "Embedding content") - WSD Blogging Server.
175
176 [Animating images with PhotoPeach](http://comohago.conectandonos.gov.ar/2009/08/05/animando-imagenes-con-photopeach/ "Animando imÔgenes con PhotoPeach") - Cómo hago.
177
178 == Installation ==
179
180 Code Embed can be found and installed via the Plugin menu within WordPress administration (Plugins -> Add New). Alternatively, it can be downloaded from WordPress.org and installed manually...
181
182 1. Upload the entire `simple-embed-code` folder to your `wp-content/plugins/` directory.
183 2. Activate the plugin through the 'Plugins' menu in WordPress administration.
184
185 Voila! It's ready to go.
186
187 == Frequently Asked Questions ==
188
189 = My code doesn't work =
190
191 If your code contains the characters `]]>`, then you'll find that it doesn't - WordPress modifies this itself.
192
193 Also, check to see if the post has been modified by a user without `unfiltered_html` permissions - if it was, they may have caused the code to have been modified (see the "Filtering of code" section above).
194
195 Otherwise, it's likely to be your code and not this plugin. The best way to confirm this is to look at the source of the page and compare the code output with what you embedded. Does it match? If it does, then your code is at fault.
196
197 = What's the maximum size of the embed code that I can save in a custom field? =
198
199 WordPress stores the custom field contents in a MySQL table using the `longtext` format. This can hold over 4 billion characters.
200
201 = Can I use the same embed name on multiple pages? =
202
203 Yes, you can. If you wish to share one set of embed code across multiple posts, though, then you need to give it a unique name (see "How to Use Global Embedding", above).
204
205 = Is this GDPR compliant? =
206
207 It is, in that it doesn't save any data that could be at odds with GDPR compliance (i.e. it's compliant by design). However, if you use this to embed third-party scripts, then those scripts may not be and you will need to speak to the providers for further details.
208
209 = Do you support this plugin on forks of WordPress? =
210
211 No. It was developed for WordPress, and so forks remain unsupported. I have no intention of developing and testing this on any other version.
212
213 = Where do I report security bugs found in this plugin? =
214
215 Please report security bugs found in the source code of the Code Embed plugin through the [Patchstack Vulnerability Disclosure Program](https://patchstack.com/database/vdp/9e5fb3d8-2b30-4f96-919c-ecbc8308eda4). The Patchstack team will assist you with verification, CVE assignment, and notify the developers of this plugin.
216
217 == Screenshots ==
218
219 1. The options screen
220 2. The custom field meta box with a Code Embed field set up to show some YouTube embed code
221 3. Example embed code in a post
222 4. The block editor Settings screen showing the Custom field switch at the bottom
223 5. The search screen showing the results of a search for {{CODE1}}
224
225 == Changelog ==
226
227 I use semantic versioning, with the first release being 1.0.
228
229 = 2.6.4 =
230 * Security: As you'll have seen from recent releases, there's been a long stream of reported vulnerabilities. We can probably blame/thank AI for this. So, as a pre-emptive strike against more occurrences, I've done a thorough security scan and update. It's not finished because, as I was working through things, another vulnerability was reported, which is included in this change...
231 * Security: Fixed a reported security vulnerability. Fixing this has meant 2 changes in how the plugin works, which are noted at the top of this README
232
233 = 2.6.3 =
234 * Security: Fixed [a stored XSS vulnerability](https://github.com/dartiss/code-embed/security/advisories/GHSA-qrwc-v5hh-f395) that was reported by [pphreak-1001](https://github.com/pphreak-1001)
235
236 = 2.6.2 =
237 * Security: Fixed a vulnerability, reported by an automated security review from WordPress.org
238
239 = 2.6.1 =
240 * Security: Fixed CVE-2026-48093, as reported by [manop55555](https://github.com/manop55555), as the code was vulnerable to stored Cross-Site Scripting (XSS) through the external URL embed feature in post content.
241
242 = 2.6 =
243 * Enhancement: A massive review of the code means that it now conforms to WCAG 2.1 AA standards, and is more secure and performant than ever before.
244 * This is not the end to improvements, however, and expect 2.7 to drop soon with even more quality-of-life enhancements, as well as all the bugs squashed that have been reported to me.
245
246 = 2.5.2 =
247 * Security: Fixed CVE-2026-2512, as reported by [Muhammad Yudha](https://www.wordfence.com/threat-intel/vulnerabilities/researchers/yudha) via [WordFence](https://www.wordfence.com/r/26c227ba3ee33458/).
248
249 = 2.5.1 =
250 * Security: Changed `wp_remote_get` to `wp_safe_remote_get` to improve security.
251
252 = 2.5 =
253 * Enhancement: This release is a revised version of 2.4, with less impact on other plugins and users. See the README for more details, but this undoes the changes in 2.4 and adds in filtering of code embed fields for users without the correct permissions.
254 * Bug: Fixed a long-standing bug that could cause an infinite loop to occur in rare situations.
255
256 = 2.4 =
257 * Security: A vulnerability was reported to me but is actually an issue with Core. I've implemented a fix that protects not just this plugin but any others you may have installed. Please read the section in the README titled "Custom Field Security" for more details.
258 * Enhancement: Tweaked a few bits of code here. No visible changes, just quality improvements.
259
260 = 2.3.9 =
261 * Enhancement: So, let me tell you a story. To make the output look neat, I was adding carriage returns to the embeds. Except, if you want to embed something partway through a line it can look... well... wrong. And all for it looking clean. Remember, kids, cleanliness isn't always next to Godliness. Needless to say, those rogue carriage returns are gone.
262 * Enhancement: While I was at it, I updated some of the settings code to a brand-spanking new version, which I'm sharing across all my plugins.
263 * Enhancement: Tidied up some of the assets, including adding a blueprint for WordPress Playground.
264
265 = 2.3.8 =
266 * Bug: You know that vulnerability I fixed in 2.3.7? It fixed that but broke something else. That should now be resolved. Apologies for that.
267
268 = 2.3.7 =
269 * Bug: Fixed a bug that created a potential vulnerability.
270 * Enhancement: Improved code quality, using the latest version of PHPCS and WordPress sniffs.
271
272 = 2.3.6 =
273 * Bug: Fixed a variable that was incorrectly assigned. It happens. I guess.
274
275 = 2.3.5 =
276 * Enhancement: Cleared up a big batch of code quality issues. Now it ticks all the boxes for both the WordPress and VIP rulesets in PHPCS.
277 * Enhancement: A new, richer, header has been added to the plugin file.
278 * Enhancement: The plugin version number is now used as a revision for the script queueing - this means that it will be cached by the browser until the plugin release changes.
279 * Enhancement: Lots of changes made to the README - hopefully it should read more easily than before!
280
281 = 2.3.4 =
282 * Bug: Fixed a minor error that occurred due to the removal of the debug code in the last release. Sorry about that.
283
284 = 2.3.3 =
285 * Enhancement: I've removed the debug code. I allowed it to be switched off but I've never used it and it may not have switched off properly anyway. So it's gone.
286 * Enhancement: Added some additional plugin meta.
287
288 = 2.3.2 =
289 * Bug: Fixed another pesky bug that was affecting embedded URLs. My code to do this was years old and I couldn't understand why I'd written it the way I had. So I've rewritten it from scratch.
290
291 = 2.3.1 =
292 * Bug: Fixed a variable naming issue that I may, or may not (I did), have created in the latest release.
293
294 = 2.3 =
295 * Enhancement: All the code is now compliant with the full-fat VIP coding standards. It was no mean feat but, as a result, the plugin is more secure than ever before.
296 * Enhancement: The default is to now use double braces around your embed name, which is essentially the universal default for template tags such as this. If you're an existing user, your current configuration won't change, though - this only affects new users.
297 * Enhancement: Improved translation output, including where I'd accidentally added an extra character to the text domain.
298 * Enhancement: Using the `checked` function on fields, rather than the form parameter.
299 * Enhancement: Added a useful links sidebar to the Help for both screens.
300 * Maintenance: Throughout, use Yoda conditions I now do.
301 * Maintenance: Added links to the sparkly new Github repo.
302 * Bug: When updating the options you sometimes didn't get a confirmation message. You do now!
303 * Bug: Fixed a weird one where I was referencing a variable that I was never using.
304
305 = 2.2.2 =
306 * Maintenance: Updated README to work better with new plugin directory format. Also, now converting all text to US English, which is the WordPress standard. Snazzy.
307 * Maintenance: Updated all links to artiss.blog and removed donation links. Clickable.
308 * Maintenance: Minimum WordPress level is now 4.6 for this plugin, meaning I could remove various pieces of code. Strong and stable.
309 * Maintenance: Lots of language updates, many of which are a consequence of the move to WordPress 4.6 (including removal of language files and links, etc.). Verbose.
310
311 = 2.2.1 =
312 * Maintenance: Updated branding, including adding donation links.
313
314 = 2.2 =
315 * Enhancement: Added support for embedding code in excerpts.
316 * Enhancement: Validated, sanitized and escaped the admin screen data.
317 * Maintenance: Overhauled the way default options are fetched and/or generated. Now a lot more efficient.
318 * Maintenance: Updated the admin screens so they are formatted in a similar way to the default WordPress screens.
319 * Maintenance: Removed hardcoding of plugin folder.
320 * Maintenance: Updated author and removed donation links.
321 * Maintenance: Renamed files and file functions - removed prefix from files and updated it on functions.
322 * Maintenance: Added a domain path for translations.
323
324 = 2.1.2 =
325 * Maintenance: Added missing text domain, ready for automatic translation.
326
327 = 2.1.1 =
328 * Maintenance: Updated help text.
329 * Maintenance: Modified admin screen headings so they're compatible with WP4.3.
330 * Enhancement: Added options to suppress debug output.
331 * Enhancement: Added donation link to plugin meta. Go on, you know you want to!
332
333 = 2.1 =
334 * Maintenance: Updated plugin branding.
335 * Maintenance: Removed feature pointer - no longer required.
336 * Enhancement: Removed support screen and moved remaining admin screens.
337 * Bug: Fixed issues with translations.
338
339 = 2.0.2 =
340 * Enhancement: Fixed a [minor XSS vulnerability](https://bugzilla.mozilla.org/show_bug.cgi?id=771315 "Bug 771315 - WP Plugin Simple-embed-Code - Fix XSS Before Adding to Hacks Blog") (kindly reported by Mozilla).
341 * Enhancement: Shows README appropriate to the current installed version, instead of the latest.
342
343 = 2.0.1 =
344 * Enhancement: Removed restriction on embed code length.
345
346 = 2.0 =
347 * Maintenance: Removed dashboard widget.
348 * Maintenance: Further code tidying.
349 * Maintenance: Added new code for contextual help to use new WP 3.3 elements.
350 * Enhancement: New admin menu option, under which existing option screens now exist along with a support screen. If you have the [README Parser plugin](http://wordpress.org/extend/plugins/.wp-readme-parser/ "README Parser") installed, then it will also add a sub-menu displaying README instructions.
351 * Enhancement: Added internationalization to code.
352 * Enhancement: Will now work with widgets if you install the plugin [Widget Logic](http://wordpress.org/extend/plugins/widget-logic/ "Widget Logic").
353 * Enhancement: Added experimental ability to convert to responsive output.
354 * Enhancement: Added option to specify a URL instead of an embed code.
355 * Enhancement: Added feature pointer for when plugin is activated.
356
357 = 1.6.1 =
358 * Bug: Fixed bug where name of plugin folder was incorrect.
359
360 = 1.6 =
361 * Maintenance: Improved code further from 1.5, including separating code into separate includes.
362 * Enhancement: Added global embeds option.
363 * Enhancement: New tools option in the administration menu that allows you to search for code embeds.
364
365 = 1.5.1 =
366 * Enhancement: Added form security.
367
368 = 1.5 =
369 * Maintenance: Renamed plugin to bring in line with new plugin conventions.
370 * Maintenance: Plugin rewrite to create more efficient code - can now also completely personalize the embed code used in the post.
371 * Maintenance: PHPDoc used throughout for documentation purposes, plus new coding standards.
372 * Maintenance: Instructions completely rewritten.
373 * Enhancement: Support information improved, including contextual help on the settings screen (if supported).
374
375 = 1.4.1 =
376 * Bug: Version details as HTML comments were being output whether an embed existed or not - corrected.
377
378 = 1.4 =
379 * Enhancement: Option screen that allows you to specify the maximum number of possible embeds per post and the embed word.
380
381 = 1.3 =
382 * Enhancement: Increased limit of number of code embeds from 5 to 20.
383
384 = 1.2 =
385 * Maintenance: Simplification of code.
386
387 = 1.1 =
388 * Maintenance: The instructions have been corrected. Thanks to John J. Camilleri for pointing it out!
389 * Maintenance: Plugin has been tested with version 2.8 of WordPress. No code changes have been made.
390
391 = 1.0 =
392 * Initial release.
393
394 == Upgrade Notice ==
395
396 = 2.6.4 =
397 * Security hardening and a vulnerability fix