Paragraph Settings

Insertion before or after paragraphs is one of the most commonly used functions of the plugin. Paragraph settings allow you to very precisely define what is considered as paragraph, how they are counted and where should insertion be avoided. Similar settings are available also for insertion before or after images.

Please check all the available paragraph settings in order to get the most out of the plugin.

Insertion Before/After paragraph works mainly on posts and pages. It uses the_content filter hook to process post content and insert blocks. Some themes may use the_content filter hook also for content on block pages (e.g. homepage, category page, etc.). Use tool to check for available positions to see where you can use individual insertion.

Insertions before or after paragraphs are always done server-side – when the page is created. This means that all the paragraph counting and clearance settings are applied when the theme calls the_content filter hook and then each block (using paragraph settings described below) is inserted starting from block 1 to block 96. This is especially important when you are using clearance options to avoid insertions near other Ad Inserter blocks or when other plugins insert their stuff into the content. Ad Inserter is called last (default plugin priority is 99999), however, some content may still be inserted later or even client-side (in the browser).

Insertion Before/After paragraph can also be used with Ajax calls (infinite scroll), however, the plugin or theme responsible for infinite scroll (response to Ajax requests) should use the_content filter hook to process the content before returing it in response to Ajax requests.

Paragraph / Image number(s)

Here you define paragraph numbers for Automatic Insertion options Before and After Paragraph – you can specify comma separated list of paragraph numbers for multiple insertions:

• value 1 or more means paragraph number
• negative value -1 or less means paragraph number counted from the opposite direction as configured
• value between 0 and 1 means relative position in post or page (e.g. 0.3 means paragraph 30% from top or bottom)
• negative value between -1 and 0 means relative position in post or page counted from the opposite direction as configured (e.g. -0.3 means paragraph 30% from the bottom if Count is set to From Top)
• paragraphs in square brackets [] mean possible paragraphs for random selection (single insertion): you can list individual paragraphs (e.g. [4, 5, 6]), paragraph ranges (e.g. [4-6]) or comma separated list of paragraphs and ranges (e.g. [4, 5, 8-12]). 0 or []  as paragraph number means one random paragraph among all available paragraphs (according to the paragraph counting). For each random selection one paragraph number will be selected and this is where the insertion will take place. You can also list fixed paragraph numbers and possible paragraphs for random selection, for example 3, 6, 9, [12-15], 18, [21-24, 26, 27] means paragraphs 3, 6, 9, one random paragraph between 12 and 15, 18 and one random paragraph between paragraphs 21, 22, 23, 24, 26, 27.
• %N means insertion every N paragraphs
• %N@S means insertion every N paragraphs starting from paragraph S
• Empty value means all paragraphs – use Filter to define insertions

The same settings as for paragraph numbers can be used also for image numbers.

Insertion Before/After image is equivalent to insertion Before/After paragraph using figure,img as paragraph tags and figure tag added to No paragraph counting inside tag list (in case it is not present there). This ensures the ad will not be inserted between actual image and image caption (if used). If you need to refine settings for insertion before/after image you can switch insertion to Before/After paragraph, use paragraph tags listed above and then define additional conditions described below (of course, word counting settings do not apply to images).

Next to field for paragraph numbers there are also two buttons for additional paragraph settings: Counting and Clearance.

Counting

Insertion inside post/page content is possible only before or after paragraphs (or images). However, there are many powerful settings to define what should be counted as a paragraph.

Paragraphs can be counted from top or from bottom. You can define HTML tags which are considered as paragraphs. Normally only p tags are used. If your post contains also div or header tags, you can define comma separated list of tags used to count paragraphs (e.g. p, div, h2, h3).

It is also possible to count only paragraphs that contain or do not contain certain text or count only paragraphs that have some minimum or maximum number of words.

If more than one text is defined (comma separated) and contain is selected then the paragraph must contain ALL texts.

If more than one text is defined (comma separated) and do not contain is selected then the paragraph should not contain ANY of the texts. 

With the ^ character before the text you can invert check for individual texts. This way you can create more complex conditions for paragraph counting (De Morgan’s laws can be applied to simplify counting conditions). For example:

• count text1, text2 means count paragraph if text1 AND text2 are present
• count ^text1, text2 means count paragraph if text1 is NOT present AND text2 is present
• count text1, ^text2 means count paragraph if text1 is present AND text2 is NOT present
• count ^text1, ^text2 means count paragraph if text1 is NOT present AND text2 is NOT present
• do not count text1, text2 means do not count paragraph if text1 OR text2 are present = count paragraph if text1 is NOT present AND text2 is NOT present
• do not count ^text1, text2 means do not count paragraph if text1 is not present OR text2 is present = count paragraph if text1 is present AND text2 is NOT present
• do not count text1, ^text2 means do not count paragraph if text1 is present OR text2 is not present = count paragraph if text1 is NOT present AND text2 is present
• do not count ^text1, ^text2 means do not count paragraph if text1 is not present OR text2 is not present = count paragraph if text1 is present AND text2 is present

By default paragraphs are not counted inside special elements like blockquote, figure, li. However, you can enable counting also inside these special elements and you can also define these elements – No paragraph counting inside setting (tab ⚙ / tab General). This list of elements is a general list that applies to all blocks. If the list is empty then the checkbox will not be displayed.

The fields above this checkbox contain similar settings where you can define additional block-specific elements where paragraphs should or should not be counted and you can also define text (element id, class or any other text in the paragraph) that should or should not be present in these elements. For example, if you would like to prevent inserting inside 

<code><div class="user-images">...</div>

you should set Do not count inside div elements that contain user-images and check Check only tag attributes. When this checkbox is checked only the tag attributes (like id, class, style,..) are checked. Otherwise the complete content of the paragraph is searched for the specified text.

There are four combinations possible:

• Do not count inside […] elements that contain […]
• Count only […] inside elements that contain […]
• Do not count […] inside elements that do not contain […]
• Count only […] inside elements that do not contain […]

Do not insert for the first X and last Y paragraphs enables you to prevent insertion at the beginning and at the end of the post. The paragraphs will still be counted, however, block will not be inserted there. Leave empty for no exclusion.

You can additionally define minimum and/or maximum number of post/page paragraphs. If the condition is not met then the block will not be inserted. Leave empty for no limit.

Minimum number of words in paragraphs above is an alternative way to insert ads only after some amount of text above. Leave paragraph numbers empty and define minimum number of words in paragraphs above. The block will be inserted between paragraphs where the number of words in paragraphs above the insertion is above this limit. This setting has no meaning when paragraph numbers are defined.

Paragraph processing works on every post or page according to settings. Therefore, if you enable insertion also on blog pages (home, category, archive, search pages) and your theme does not display post excerpts but complete posts, Ad Inserter will by default insert code blocks into ALL posts on the blog page (according to settings). 

Each code block you insert adds wrapping <div> element around the block code unless you use No wrapping style. Therefore, you need to take this into account when counting paragraphs with div elements. 

Before Paragraph will insert the code before specified <tag>, After Paragraph will insert the code after closing </tag>.

After Paragraph will work even if you specify tag names that have no closing tags (e.g. images using <img> tag) since Ad Inserter uses special processing for such cases. Use # as tag if paragraphs have no tags and are separated with the \r\n\r\n characters.

You can also insert before or after any HTML tag anywhere on the page. Ad Inserter supports insertion before, after or inside any HTML element.

Clearance

You can also define parameters to avoid insertion at paragraph positions where above or below there is some unwanted element (heading, image, title). This is useful to avoid inserting ads where they may not look good or where it is not allowed.

You can define in how many paragraphs above and below should the specified text be avoided. And if the text is found you can choose to either skip insertion or to try to shift insertion position up or down up to the specified number of paragraphs. If a suitable position is not found then the block is not inserted.

Please note that the plugin checks all the content from the insertion position to the specified pragraph above or below the insertion position. This is useful when you have some elements you would like to avoid between the pararaphs (elements that are not counted as paragraphs).

Paragraph counting help

When logged in as admin there is admin toolbar displayed on the top of every post and page.

Ad Inserter menu item has few debugging functions which can help you to see HTML tags and positions for automatic insertion with particular paragraph counting settings.

• Show HTML Tags visualizes HTML tags
• Show Positions shows available positions for automatic insertion. 

  Function Show Positions uses one of the configured paragraph settings for blocks configured for automatic insertion After or Before paragraph. Make sure you select the right paragraph counting settings (Show Positions sub-menu).