Automatic insertion means that the code block (or ad) will be automatically inserted on all posts or pages according to the block settings, even on new ones when created.
Ad Inserter can insert ads where other plugins fail. In the case you can’t use any of the available standard WordPress positions for insertion you can use automatic insertion before or after any HTML element on any page. If you can create CSS selector for that element then Ad Inserter can insert there. This means that you can insert any code anywhere on the page. This is one of the strongest features of the plugin.
For each code block you can also black or white-list categories, tags, post IDs, users, taxonomies, custom post types, urls, url parameters, referers, cookies, (in PRO also IP addresses and countries) or define individual exceptions to prevent insertions on some posts or pages.
Positions for automatic insertion
- Disabled (no automatic insertion)
- Insert Above Header (on all pages, after
<body>tag, available when Output buffering is enabled)
- Insert Before Post (before post or posts on blog pages)
- Insert Before Content (before post or page text)
- Insert Before Paragraph (on posts, pages and blog pages)
- Insert After Paragraph (on posts, pages and blog pages)
- Insert After Content (after post or page text)
- Insert After Post (after post or posts on blog pages, if supported by the theme used)
- Insert Before Excerpt (on blog pages if supported by the theme used)
- Insert After Excerpt (on blog pages if supported by the theme used)
- Insert Between Posts (on blog pages if supported by the theme used)
- Insert Before Comments (on posts)
- Insert Between Comments (on posts)
- Insert After Comments (on posts)
- Insert in page Footer (on all pages, before
- Insert Before HTML element (server-side insertion available only when Output buffering is enabled)
- Insert Inside HTML element (server-side insertion available only when Output buffering is enabled)
- Insert After HTML element (server-side insertion available only when Output buffering is enabled)
Automatic insertion positions described above depend on WordPress hooks (special functions) that WordPress or the theme used must call:
the_content– used for positions Before/After content, Before/After paragraphs
the_excerpt– used for positions Before/After excerpt
loop_start– used for position Before post
loop_end– used for position After post
the_post– used for position Between posts
wp_head– used for Header code (plugin settings, tab ⚙)
wp_footer– used for position Footer and Footer code (plugin settings, tab ⚙)
comments_array, wp_list_comments_args– used for positions Before/Between/After comments
When the theme calls a hook, this hook then calls plugins like Ad Inserter which can then insert code or ads at some position. If the theme does not use some hook, then automatic insertion which depends on this hook will not be available.
Ad Inserter can insert at the positions listed above only when the theme uses listed WP hooks!
loop_end may also be used at other positions where WP loops are used (for example inside a slider).
It may also happen that the theme does not call hooks (in particular hook
the_post which is used for insertion between posts) in the expected order. In such case the insertion will be limited, at a different position or not possible at all. Please use debugging function Show positions to see available positions for automatic insertion.
For single posts or pages insertion position Before Post usually means position above the post/page title, for blog pages Before Post position means position above all the posts on the blog page.
For single posts or pages insertion position After Post means position below the post/page after all the content, for blog pages After Post position means position below all the posts on the blog page.
Before and After Excerpt positions are available on blog pages only if your theme uses standard WordPress excerpts. Otherwise you’ll have to either modify theme files and use custom hooks or use insertion Before / Inside / After HTML element.
Order of insertion positions in a typical post is the following:
- [Above Header]
- Theme header
- [Before Post]
- Post Title
- [Before Content]
- Paragraph 1
- Paragraph 2
- Paragraph …
- Paragraph n – 1
- Paragraph n
- Output of some other plugins
- [After Content]
- Output of some other plugins
- [Before Comments]
- [After Comments]
- Output of some other plugins
- [After Post]
- Page footer
Insertion position Above Header inserts code after
<body> tag, while Header code in the plugin setting (tab ⚙) inserts the code (scripts) in the
<head> section of the HTML page. Insertion position Above Header needs special code processing and is available only when you enable Output buffering (tab ⚙ / General), however, this may not work with all themes.
The final order of insertion depends also on other plugins. Ad Inserter is by default called as one of the last plugins. The issue can be noticed when you would like to insert, for example, after the content but you see that your code is not inserted immediately below post content. This is because that code above yours was inserted by some other plugin (or your theme). You can change (lower) plugin priority on the settings page (tab ⚙ / tab General) for earlier processing so your code would be inserted first (use 5 as plugin priority for early processing).
Please use Show positions function to see available positions for automatic insertion (Ad Inserter menu item in the WordPress admin toolbar on the top of every post/page when logged in as admin).
To insert code block you need to use automatic or manual insertion. Once you configure settings including insertion the code will be inserted. If for some reason you need to temporarily disable (pause) insertion you can disable automatic insertion or uncheck manual insertion.
To achieve the same effect without changing the block settings you can simply disable (pause) insertion of each code block with a single button. Click on the pause button (it will be red when paused) and save settings.
Ad Inserter supports also automatic insertion at custom positions where hooks are used using the
do_action () WordPress function. The number of available custom hooks depends on the license type (free Ad Inserter supports 2 custom hooks). To define hooks go to tab ⚙ / tab Hooks:
Hook name is a name that is used in the Automatic insertion selection, action is the name that is used in the
do_action () WordPress function used in the theme and priority is the hook priority (lower number means earlier processing). You can use ANY hook that is implemented by your theme or added by plugins. After you save settings you get new positions for automatic insertion.
Hook is a standard WordPress PHP function call to allow themes and other plugins to insert custom code. Instead of inserting adinserter PHP function call you can install custom hook at any theme position:
<?php do_action ('custom_action_name'); ?>
Alternative to custom hooks is PHP function call
<?php if (function_exists ('adinserter')) echo adinserter (BLOCK_NUMBER); ?> which can insert code block BLOCK_NUMBER at any position in template file. You need to enable PHP function call for each block (button Manual).
The difference between adinserter PHP function call and custom hook is that
adinserter () PHP function will insert only the specified code block, while custom hook position is available as position for automatic insertion and can be used for any code block.
Here you define CSS selector (or comma separated list of selectors) of the HTML element(s) where you want to insert the code block (
.class). To get right CSS selector you can use web inspector in the browser or built-in HTML Element Selection tool. To open it click on the small button before the field.
Server-side insertion is the best approach, however, it requires output buffering which is by default disabled as it may not work with all themes. To enable it go to plugin settings (tab ⚙ / tab General) and set Output buffering to enabled. After you save settings you will be able to select server-side for insertion before/after HTML element.
When you select automatic insertion Inside HTML element additional setting becomes visible: Action. This action defines how the code block is inserted (or HTML element replaced):
- Prepend content – the block is added as the first child inside target element
- Append content – the block is added as the last child inside target element
- Replace content – the block replaces the content inside target element – if the block is empty it will clear the content of the target element
- Replace element – the block replaces the target element – if the block is empty it will remove the target element from the DOM
<before-element> <element> <inside-element-prepend> <first-child> <second-child> <third-child> <fourth-child> <...> <last-child> <inside-element-append> </element> <after-element>
When you are inserting HTML tags inside HTML element make sure you set Alignment and Style to No wrapping to prevent inserting
<div> wrapper around the code (tag) you are inserting. This way you can, for example, insert
<li> element inside
Output buffering means buffering the page while it is created by WordPress using your theme and plugins. After the buffering ends the buffered page content is processed and code blocks before/after HTML elements are inserted. To check if your theme supports output buffering, go to plugin settings (tab ⚙ / tab General) and enable Output buffering, then go to homepage and enable Show positions debugging function (Ad Inserter menu item in the top admin bar). If you see OUTPUT BUFFERING (and ABOVE HEADER) bar then output buffering works as expected.