Goo Include Me

Version 1.1.0.

This is an official home page with instructions of Goo Include Me plugin for WordPress

To people who builds or operate WordPress sites, current and potential users of Goo Include Me plugin

No, this software is meant for to all users of the WordPress

Table of Contents

 

 

Description

Include custom JavaScript, CSS files and custom HTML codes in a front-end of your WordPress installation, controlling their placement and insertion in various ways.

 

Insert with ease (but not limited to):

  • Google – Analytics tracking code, Page level ads code, AdSense code
  • Facebook comments code
  • Third party social buttons and scripts code
  • Custom JavaScript and/or files
  • Custom CSS and/or files
  • Custom SEO meta tags
  • Custom HTML elements

(for more detailed info please visit How To section)

 

This plugin is designed to provide additional functionality to the WordPress site, both for beginners and advanced users. The main purpose of this plugin is to include in a safe and proper way third party (or your own) JavaScript & CSS files and HTML code without modifying theme core files. Included resources become part of the plugin itself, ensuring no customization override will occur due theme or WordPress update.

From plugin admin panel control how your resources will be deployed: across all pages, only particular page/post (by post ID or multiple IDs), only selected post types (page, post, attachment or custom post type created by your theme or any other plugin), with exclusion rule marked by selected post IDs or create SHORTCODE and insert in the content wherever you desire.

By controlling which pages to include your custom resources, you are actually speeding up your site, ensuring deployment occur only where resources actually needed.

 

How to use this help file

If you are reading first time this content, please read it all, from top to bottom to get familiar with the plugin capabilities (later in the text “plugin” refer to THIS plugin: Goo Include Me if not marked otherwise).

In text below, sentences which start with (Advanced) are meant for advanced WordPress users, and usually describe internal plugin and/or WordPress mechanic.

 

Install

To install plugin go: Admin panel -> Plugins -> Add new -> Upload plugin -> Browse (and select .ZIP file) -> Install now. All you have to do now is to activate plugin.

If you omit to do it from installation page, you can always do it from Plugins page. Admin panel -> Plugins, find Goo Include Me plugin, and click Activate link right below.

 

Plugin settings

To access plugin settings page go: Admin panel -> Goo Tools Plugins -> Goo Include Me or from Admin panel -> Plugins find Goo Include Me and click Settings link just below.

 

Your screen should look similar to this:
goo_include_me_screenshot_01

Settings section contains three tabs: Script files, CSS files and Arbitrary HTML. Every file or HTML snippet you wish to include represent “rule”. Please avoid using same file or code in multiple rules, unless you really have to. Most of rule options are repetitive across all tabs, so they will be explained in the OPTIONS section.

 

Script files

Here you can control the deployment and inclusion of your JavaScript files (picture above). Every rule consist of these options: Handle, Src, Dependencies (optional), Include into, In footer and Script version. (Advanced) This plugin feature is strongly dependent on built in WordPress functions wp_register_script and wp_enqueue_script. Every rule, you create is registered at the front end of your WP installation and included in the document when prerequisites are met in Include into option.

 

CSS files

Here you can control the deployment and inclusion of your CSS files.
goo_include_me_screenshot_02Rule options are: Handle, Src, Dependencies (optional), Include into, Media and Style version, and they are very similar to Script options. (Advanced) As with Script files, this feature depend on wp_register_style and wp_enqueue_style respectively.

 

Arbitrary HTML

JavaScript code snippets and DOM elements:
goo_include_me_screenshot_03Any third party (or your own) code or DOM you wish to include goes here eg. Google Analytics code. Content can be inserted in <HEAD></HEAD> section, just right before closing BODY tag, or in post content itself. Also, you can create SHORTCODE and fully control where (in post content) do you want to include your snippet. Rule options: Caption, Code, Include into and Placement. (Advanced) Depending on the situation, plugin may use various actions and filters wp_head, wp_footer, shortcode, the_content etc.

 

Option list

Handle

| Script files || CSS files |

(string)(required) – Unique one word script/css rule name under which will be recognized and used in WordPress installation. Please avoid generic names like my_script, my_style, my_cool_script etc. since they can collide or override badly named scripts or css files used by other plugins or even theme.

examples:
	my_script - (BAD - low uniqueness)
	my styles - (BAD - not one word)
	example_com_user_enhancer_css - (GOOD - project name combined with description)
	example_com_ajax_resolver_script - (GOOD - project name combined with description)


Src

| Script files || CSS files |

(string)(optional) – The full URL of the script/style, or path of the script/style relative to the WordPress root directory. Also, path string can be enriched with additional path parsing options built in WordPress, and invoked via “wildcards”: {home_url}, {plugin_url}, {theme_url}.

 

Wildcard* values for www.example.com
	{home_url} - http://www.example.com/
	{plugin_url} - http://www.example.com/wp-content/plugins/goo-include-me/ 
	(please note that this wildcard refer to URL where THIS plugin is installed)
	{theme_url} - http://www.example.com/wp-content/themes/twentyeleven/
	(this wildcard refers to URL of your current active theme)

 

*NOTE: every wildcard contain trailing slash “/” at the end

 

You may find useful using wildcards if you plan to migrate your WP installation to another domain or change present one from HTTP to HTTPS protocol.

examples:
	custom_script_head.js - (INVALID no slash)
	/custom_script_head.js - (VALID refer to WP installation directory)
	http://www.example.com/scripts/custom_script_head.js - (VALID)
	{home_url}/custom_script_head.js - (INVALID wildcard already contain slash "/")
	{home_url}custom_script_head.js - (VALID home URL for the current site with file name)

If the plugin cannot find your file after you hit “Save Changes” you’ll see the “red box” notice:

goo_include_me_screenshot_04The plugin DOES NOT check file existence at front end (to avoid site performance drop) only in the plugin admin panel, so pay attention for this notice or you might end up in including non existing file due bad formatted URL.


 

Dependencies

| Script files || CSS files |

(string)(optional) – If your script (stylesheet) is dependent from another script (stylesheet) to run properly, this is right place to declare it. Write down all handles which your script depends on, separated by comma, or leave blank if your script is stand alone.

The most common scenario is that your script requires jQuery framework which lead us to WordPress built in scripts (these scripts are already declared in WordPress, and all you have to do is “hook” them up to your script rule). Familiarize with WordPress Core Registered Scripts and their handles.

 

“Script files” rules cannot depend on the “CSS files” rules and vice versa. If you need them both synchronized, in action you perform, create separate rules with same “Include into” pattern.

 

examples:
	jquery - jQuery core, already in WP
	my_custom_script - handle of the rule you already declared
	jquery, my_custom_script - both of above

 

 IMPORTANT: This option can override existing rules, if depend on them. Eg. if “Rule2” (placed in header) depend on “Rule1” (which is placed in the footer), “Rule1” will be loaded in the header before “Rule2” breaking own rule of inclusion, to support “Rule2” dependency.


Include into

| Script files || CSS files || Arbitrary HTML |

(string/integer)(optional) – Here you control deployment of your file or snippet to front-end pages. Although default value is set to auto (include in all front-end pages), you can create complex filtering rules of inclusion, by post types, post ID, exclude specific post ID, or a mix of them all.

 

Values:

  • auto – include in all frontend pages
  • %POST_ID% – include only in post with exact ID (how to find post id? See here)
  • -%POST_ID% – exclude from post with exact ID (usually combined with other inclusion rule)
  • singular(%post_type1%, %post_type2%, …) – include in listed single page post types (if %post_type% omitted, include in all single page post types)

 

Post types available to you are listed, just under the tabs:

goo_include_me_screenshot_05This particular WP installation also contains custom post types created by WooCommerce plugin.

 

Understanding “singular” pages -Page which displays full and only the content of specific post, page or any other post type is singular.

-Pages which list posts by specific term and contain multiple post content in their full or shorten length are NOT considered singular. Eg: “When a viewer clicks on a link to one of the Categories on your site, he or she is taken to a page listing the Posts in that particular Category in chronological order, from newest Posts at the top to oldest at the bottom.”… WordPress CODEX

 

examples:
	auto - include in every page
	1533 - include only in post with 1533 ID
	auto, -1247 - include in all pages, except page with 1247 post ID
	singular() - include in all pages with single content
	singular(post) - include only in "post" type pages
	singular(post, page) - include only in "post" and "page" type pages
	singular(product), -56 - include in "product" type pages, but not product with ID 56
	1244, 857, 50 - include in posts with listed IDs
	_____ - leaving blank will turn off that rule, but other rules can depend on it

 


 

In footer

| Script files |

(bool)(required) – Choose where loading of script file will occur.

Values (In footer):

  • No – script file will be invoked in <HEAD></HEAD> section of document
  • Yes – script file will be invoked just before closing </BODY> tag

(Advanced) Some themes extensively use wp_enqueue_script and wp_dequeue_script and can override your desired placement.


 

Script/Style version

| Script files || CSS files |

(string)(optional) – String specifying script version number, if it has one, which is added to the URL as a query string for browser cache busting purposes. Every time you made changes in your script/css file, slightly increment version number, forcing browser to properly apply changes by reloading the complete file.

(Advanced) As mentioned before, the version number will be added to URL query, and, by changing it, the browser will see completely different URL which will trigger loading file (rather than using it from browser cache), thus, applying all changes you made.


 

Media

| CSS files |

(string)(required) – The media attribute specifies what media/device the CSS style is optimized for. Default is ‘all‘.

More info here.


 

Caption

| Arbitrary HTML |

(string)(required) – Similar to the ‘Handle’, Caption defines a rule name for arbitrary HTML. Also, the caption is base name for your SHORTCODE you wish to create.


 

Code

| Arbitrary HTML |

(string)(required) – Insert here third party or your own code you wish to include. The code itself can contain various scripts or styling rules, DOM elements, etc. Be aware of proper placing, because effective use of the “code” can strongly depend on it.

  • HTML – allowed
  • JavaScript – allowed
  • PHP – NOT allowed !!!
  • any WordPress shortcode – allowed, and will be processed as usual [SHORTCODE] you deploy in page/post editor

VERY IMPORTANT! – Plugin developers are NOT in any way responsible for “code” you are applying, or potential damage such “code” can cause to you or your visitors. Please, use code snippets from trustful sources at your own discretion, and/or test functionality and behavior in a controlled environment.


 

Placement

| Arbitrary HTML |

(string/select)(required) – Where and how do you want to include your “code” in the page.

Values:

  • Header – place “code” in <HEAD></HEAD> section of a document
  • Footer – place “code” right before closing </BODY> tag
  • Content-Beginning – insert “code” just before post content, as a part of post content itself.
  • Content-End – insert “code” just after post content, as a part of post content itself.
  • Content-Shortcode – Create SHORTCODE from this rule. Placing manually shortcode anywhere in post/page editor will trigger “code” insertion. This placement value TURNS OFF and overrides any value in “Include into” section of the rule.

 

How to use SHORTCODE you just created with Content-Shortcode option?

The syntax for your custom shortcode is:

[goo-include-me %RULE_CAPTION%]

Also, you can invoke multiple shortcodes with a single pair of square bracket:

[goo-include-me %RULE_CAPTION_01% %RULE_CAPTION_02%]

…which is basically same as:

[goo-include-me %RULE_CAPTION_01%] [goo-include-me %RULE_CAPTION_02%]

 

Notice: Only rules with a placement value set to Content-Shortcode can be invoked as shortcodes, to prevent possible misuse of other rules or doubling code inclusion.


 

How to

This section covers some of the possible scenarios of the plugin usage. Please be advised, third party code we used here may have changed alongside with deployment requirements of the same over time.

We strongly recommend you to familiarize first with an updated version of a guide and documents provided by third party code authors before you try to replicate scenarios below.

Parts of the images we display here are blurred (and usually cover third party code), for various reasons: we do not own code, but it’s granted or leased to us; may contain sensitive information not relevant to you or tutorial itself; might be copyrighted material etc.

Almost all examples can be modified to fit your needs. Experiment until you reach the desired effect.

Insert Google Analytics code

description: “Google Analytics is a freemium web analytics service offered by Google that tracks and reports website traffic. Google launched the service in November 2005 after acquiring Urchin. Google Analytics is now the most widely used web analytics service on the Internet.”

prerequisites: Google account, declared/claimed property in Google Analytics

The content of this tutorial has been moved to a separate post. Please follow this link.

Insert Google Analytics code with Goo Include Me plugin

Insert Google AdSense code to all posts

description: AdSense (Google AdSense) is an advertising placement service by Google. The program is designed for website publishers who want to display targeted text, video or image advertisements on website pages and earn money when site visitors view or click the ads.

prerequisites: Google AdSense account, familiar with creating ad units

The content of this tutorial has been moved to a separate post. Please follow this link.

Insert Google AdSense code to all posts with Goo Include Me plugin

Apply Datepicker (jQuery UI)

description: The datepicker is tied to a standard form input field. Focus on the input (click, or use the tab key) to open an interactive calendar in a small overlay.

prerequisites: understanding jQuery UI (datepicker), more info here.

The content of this tutorial has been moved to a separate post. Please follow this link.

Apply Datepicker (jQuery UI) with Goo Include Me plugin

Include Facebook comments plugin in every post

description: The comments plugin lets people comment on content on your site using their Facebook account. People can choose to share their comment activity with their friends (and friends of their friends) on Facebook as well. The comments plugin also includes built-in moderation tools and social relevance ranking.

prerequisites: Facebook account, Facebook App key

The content of this tutorial has been moved to a separate post. Please follow this link.

Include Facebook Comments Plugin in every post with Goo Include Me plugin

Something to say...

Pin It on Pinterest

Share This