Code Editing

Ad Inserter can be configured to insert any code anywhere on the page. Each code with its settings is called a code block.

The settings page is divided into tabs – 16 code blocks and plugin settings. Black block number means inactive code block (code is not inserted anywhere – no insertion is used or PRO scheduling is not active), red number means block is using automatic insertion, blue number means block is using manual insertion while violet number means block is using automatic and manual insertion.

Each code block has a name (click on it for editing), code and settings which are divided into sections. Some settings depend also on automatic insertion used. When you are finished with settings you need to save them by clicking on the button Save Settings.

To show block ranges and a list of all blocks click on the Blocks button in the header row.

The list will show block number, block name, Automatic insertion and icons for some block functions that are enabled: PHP code processing, individual post/page exceptions, device detection, scheduling, tracking (Pro only), limits (Pro only), PHP function call, shortcode and widget. When widget is actually used in some widget position (sidebar), the list will also show widget position name(s) where the widget is used.

To filter blocks enter keywords in the search field on the left. You can also use partial block names, php, shortcode or widget keywords to filter blocks that have enabled respective functions. This list by default shows all active blocks. To show all blocks (active and inactive) click on the active/all button:

To preview block click on the small play button left of the block number.

To pause a block (disable insertion) click on the small pause button left of the block number.

This action is automatically saved! You don’t need to save settings for the change to take effect.

Here you can also easily rearrange block order. Click on the Rearrange block order button to enable moving blocks.

Now you can drag and move blocks to swap blocks or create new block order. The position where the block would be moved is highlighted.

When you are happy with the order click on the Save button.

Click again on the Rearrange block order button to cancel changes. When you save new block order this changes also Ad Inserter widget blocks in widget positions, fallback blocks and statistics data accordingly.

When block has default name (it was not renamed) the default name of block will remain according to the block number (it will not be moved with the block).

Please make sure tracking and caching are disabled before you rearrange block order!

PRO Ad Inserter Pro supports additional feature to pin block list. When the list is pinned it is always visible on the right side of the plugin settings:

Header toolbar

On the top of the settings page there is a small window showing plugin name and version on the left and a toolbar with buttons for some Ad Inserter functions on the right.

The first button opens online documentation page in a new tab.

When AdSense integration is enabled, AdSense button opens a list of your AdSense ad units.

With Ad Inserter you can also create or edit ads.txt file.

Ad Inserter can insert any code anywhere on any WordPress page. However, automatic insertion depends on your theme and positions (action hooks) supported by your theme. This button opens a tool that can check for available positions for automatic insertion.

The last button shows buttons to toggle block ranges and opens a list of all blocks as described above.

Block name

To rename code block click on the name for editing.

 

Block code

Ad Inserter provides many simple functions to generate, edit or copy codes for ads. You can simply paste the code you have generated elsewhere, create code for banners or text ads or copy and edit code form other code blocks.

Paste only the code you know it is safe and comes from the known ad vendors! The website administrator can disable use of unfiltered HTML and Javascript code on the site. This is done for security reasons in order to prevent inserting arbitrary HTML/Javascript code which may harm the website. If you get a warning message Unfiltered HTML is disabled for this website, then you can’t use Javascript code (<script> tags) which is used by most ad codes. You need to make sure the constant DISALLOW_UNFILTERED_HTML is not defined – check wp-config.php file and settings of security plugins. For details please contact website administrator.

Quickly disable (pause) insertion

To insert code block you need to use automatic or manual insertion. Once you configure settings including insertion the code will be automatically 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 settings you can simply disable (pause) insertion of each code block – click on the pause button (it will be red when paused) and save settings. For debugging purposes you can also disable (pause) insertion for all blocks with one button – check back-end debugging for details.

To pause a block (disable insertion) you can also click on the small pause button left of the block number in the block list.

This (pause) action on the block list is automatically saved! You don’t need to save settings for the change to take effect.

Simple editor for mobile devices

On mobile devices some functions like text selection, copy and paste may not work with default syntax highlighting editor. In such case enable simple editor to switch to plain text editor.

PHP code processing

If you have PHP code (surrounded with PHP tags <?php … ?>) in code block, you need to enable PHP code processing. For debugging purposes you can disable PHP processing for all blocks with one button – check back-end debugging for details.

The website administrator can disable theme/plugin file editing by defining PHP constants DISALLOW_FILE_EDIT or DISALLOW_FILE_MODS. The same can be achieved by enabling security options in plugins like iThemes Security. In such cases the PHP processing button will not be available – PHP code will not be executed.

To enable PHP processing in Ad Inserter you need to make sure PHP constants DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS are not defined. Check wp-config.php file and settings of security plugins.

If the website can’t be loaded because of errors in your PHP code you can disable PHP processing by defining a constant, for exampe in wp-config.php file:

define ('AI_NO_PHP_PROCESSING', true);

By default PHP code in blocks is cached. The first time the code is executed whatever the code returns will be cached. This is done to prevent issues when the block is inserted more than once. Please note that the block PHP code executes even before the block is actually inserted! In the case you need to disable caching of block PHP code you need to add the following code – replace BLOCK_NUMBER with the number of your block where this code is used:

global $ai_wp_data; 
$ai_wp_data [AI_BLOCK_PHP_CODE_CACHING][BLOCK_NUMBER] = false; // replace BLOCK_NUMBER with the number of your block where this code is used

Code tools

You can edit the code in the code window but there are also additional tools to help you creating, editing and copying the code. To show the toolbar click on the code tools (wrench) button.

Code generator

Code generator currently supports code for banners and AdSense. To open code generator click on the code generator button.

Banners

Ad Inserter has a simple code generator for banners. Here you can easily add a link to the image and when using ad rotation you can rotate images with links. Code generator fields allow you to select image, define alt text, enable lazy loading, optionally define image link (web page address that will open when the banner will be clicked) and select whether to open the link in a new tab.

If you already have a banner HTML code in the code window you can import it by clicking on the import button. A thumbnail will be displayed next to the banner fields.

 

Once you are happy with the banner you can generate the code for it by clicking on the generate button. The plugin will generate HTML code for the banner in the code window of the current block.

If you have active rotation editor the code window shows only the code for the currently selected option. Therefore, code generator will in such case import or generate code only for the currently selected option.

Code generator for banners and AdSense generates the code only when you click on the button Generate code. It is a tool that can help you to create code for AdSense or banners with links. So if you are using rotation editor and switch between options you need to (optionally) import and generate code for each rotation option.

Optionally, you can add a nofollow attribute (rel="nofollow") to the link to indicate to search engines that this link should no be followed and not to use the link for page ranking calculations.

Placeholders

If you don’t have banner image ready yet you can use placeholder images to create ad positions. Ad Inserter has built-in placeholder generator/editor to easily select dummy image of any size or color. Click on the Select Placeholder button to open placeholder editor.

Choose between predefined ad sizes or define custom size. Default placeholders are gray with size as placeholder text but you can use any color or text you want. Click on the Edit button to edit placeholder size, color or text. You can also create blank solid color rectangles by clearing placeholder text.

Once you are happy with the placeholder click on the Use button to generate placeholder image url.

AdSense

Ad Inserter has a simple code generator for AdSense ads. Here you can define data needed for the AdSense code. In most cases it will be much easier to simply paste AdSense code into the code window and then import the data from it. Check AdSense Ads implementation guide for details.

This tool is mainly intended to change the type of AdSense ads. But please note: not all conversions are possible. You can convert standard ads to link ads or vice versa, fixed width ads to responsive ads and vice versa and you can enable or disable ads on AMP pages. Once you have the Publisher ID and Ad Slot ID entered (or imported) you can change ad type, responsiveness and ad type for AMP pages.

Once you are happy with the settings click on the generate button and the plugin will generate Javascript code for the AdSense ad in the code window of the current block.

Amazon

Ad Inserter has also a simple code generator for Amazon ads. Here you can define data needed for the Amazon code and optional parameters for AMP ad. In most cases the best approach is to simply paste Amazon ad code into the code window and then import the data from it. 

This tool is mainly intended to generate AMP code for Amazon native shopping ads.

Leave width field empty for responsive code (ad block occupies available width). Once you are happy with the settings click on the generate button and the the plugin will generate code for the Amazon native shopping ad in the code window of the current block.

Check also documentation on Amazon AMP ad codes.

The A9 amp ad unit supports the Search, Recommendation and Custom ad widgets of the Native Shopping Ads program. These widgets would need to be created first.

Rotation Editor

To rotate different ad versions separate them with [ADINSERTER ROTATE] – Ad Inserter will randomly select one of the ad versions. For example, to rotate 3 different images you can use the following code: 

<img style='height: 400px;' src="http://malsup.github.io/images/p1.jpg">
[ADINSERTER ROTATE]
<img style='height: 400px;' src="http://malsup.github.io/images/p2.jpg">
[ADINSERTER ROTATE]
<img style='height: 400px;' src="http://malsup.github.io/images/p3.jpg">

However, there is an easier way to create code for rotation. Use rotation editor available on the code tools toolbar.

Rotation editor will AUTOMATICALLY import rotation code from the code window (if present). In our case it would generate three options: A, B and C. You can use + and – buttons to add or remove options. 

Before saving the settings you need to close rotation code generator to generate rotation code with  [ADINSERTER ROTATE] separators – this is the rotation code you can save.

If you code contains [ADINSERTER COUNT] or [ADINSERTER CHECK] shortcode separators then you can not use ad rotation code editor as these separators have higher priority than [ADINSERTER ROTATE] separator. Use another empty block to generate rotation code if you need to use ad rotation with [ADINSERTER COUNT] or [ADINSERTER CHECK]separators.

You can also specify rotation share (percentage) for each option. If you omit one share value it will be automatically calculated. Leave Share field empty for all options to have equal shares of all rotation options.

Ad Inserter supports also timed rotation – for each option you can define rotation time. When at least one option has defined time, the plugin will generate client-side code (using CSS / javascript code) that will show one option for the time specified. If an option has no time defined the rotation will stop there. If you set time to 0 then this option will be skipped. When you define also share values for timed rotation, share values will be used only for the initial display of the first chosen option.

When rotation editor is active the code window shows ONLY code for the selected option. For each option you can copy/paste code, use Banner/AdSense code generator or visual HTML editor. Each option can also be named. This name is then used in statistics reports (PRO only) and is displayed when debugging function Label blocks is used.

When switching rotation options and using code generator you need to import (and generate) code manually for each option.

Once you are happy with the rotation settings click on the rotation editor button and the the plugin will generate rotation code in the code window of the current block. Now you can save settings.

Do not save settings when the rotation editor is active – after you are finished with rotation settings click on the rotation button to generate rotation code with [ADINSERTER ROTATE] separator.

Required steps to edit rotation code with rotation code generator:

• Open rotation code generator – it will import existing rotation code
• Add or remove rotation options
• Switch to rotation option that needs editing
• Enter option code or use banner / AdSense code generator
  • Optionally import existing banner or AdSense code from rotation option
  • Edit banner or AdSense code
  • Generate banner or AdSense code for rotation option
• Switch to another option and repeat the steps above until all options are set
• Close rotation code editor to generate rotation code
• Save settings

If you are using caching ad rotation by default may not work as expected. It works only when the page is generated and Ad Inserter is called. In such cases please make sure you have disabled caching or use client-side rotation – but you need to be aware of how it works. Please check section Caching – Ad rotation for details.

Ad Inserter is perfect for displaying any kind of ads. It can also be used to display various versions of ad, for example AdSense ads using channels to test which format or color combination performs best – but please, in such case set Dynamic blocks to either Server-side or Client-side insert.

Rotation groups

With rotation code editor you can create also groups for rotation. You can switch to rotation groups with the button next to Remove / Add option buttons.

When you switch to rotation groups Option name changes to Group name and time and share fields are hidden. Everything else is the same as for rotation options described above.

Visual HTML editor

Ad Inserter has also standard WordPress visual HTML editor to create or edit image or text ads. The button for it is located on the code tools toolbar.

The editor opens in a new window where you can edit the code the same way as you edit WordPress posts and pages. You can insert images and switch between visual editor and source code. There are also three additional buttons:

• Use copies current code to the code window and closes visual code editor
• Reset resets the code in the editor to the code from the code window in current block settings
• Cancel cancels editing and closes visual code editor

Clipboard

Ad Inserter has internal clipboard which can be used to copy and paste block name, code and settings. The buttons are located on the code tools toolbar.

Copy button copies current block to the internal clipboard. Once the block is copied the button copy is highlighted.

You can then switch to any of the remaining blocks and paste either block name, code, insertion settings or everything: name, code and settings.

To clear block settings click on the Clear block button.

With buttons in the code tools toolbar you can copy settings from any of the 16 displayed code blocks. But you can also copy settings from any other code block. Click on the Blocks button in the header to show the list of all (or only active) blocks.

Click on the copy button left of block number copies block settings to the internal clipboard. Then you can use paste functions to paste name, code, settings or complete block.

PRO Backup/Restore plugin settings

Ad Inserter settings are stored in the ad_inserter option in the wp_options table in the database. To copy complete Ad Inserter settings you need to copy this option. However, Ad Inserter Pro supports also exporting and importing plugin or individual block settings via the settings page. This can be used to transfer settings from one website to another or to create backup of plugin settings. To copy block settings to another block on the same website use Ad Inserter clipboard described above.

Backup/restore all plugin settings

You can easily save and load complete Ad Inserter Pro settings – the import/export button is located on the plugin settings tab ⚙. The window below contains encoded plugin settings. You can save this text to a file or clear the window and paste new settings here – check Import plugin settings to import and store plugin settings to the database. You can also load the settings from a file or store the settings to a file using the buttons above the settings window:

Backup/restore individual block settings

Click on the code tools (wrench) button and then on the export/import button with up/down arrow on the left to open import/export window with saved settings for this block including block code – the settings are exported as a text – a long string of characters. To import saved settings clear the the import/export window in the destination block, paste exported settings (text), check Import settings for block and click on the Save settings button. If you leave Import block name checked the import will copy also the name from the source block.

Steps to export settings – source site

• Click on the export/import button
• Window with text (encoded settings) is displayed
• You can copy and save this text to a file or import it on another website

Steps to import settings – destination site

• Click on the export/import button
• Window with text (encoded settings) is displayed
• Clear this text and paste exported settings (text) from the source website 
• Check Import settings checkbox to import settings
• Save settings

To copy settings from one block to another inside the same block range you can use internal clipboard.