Maddos Theme for WordPress

created: June 24th, 2016
http://www.superblogme.com/maddos-theme/
Release version: 2.7 - Change Log
by: Super Blog Me

Thank you for purchasing the Maddos Theme!

Maddos is directory style review theme for WordPress with header, content, and footer sections. It is especially useful for getting the visitor to an external product or content page to generate traffic and sales. It has a flexible layout where a Directory page showcases categories and their posts in the Maddos style. Each post link is to the external site url and/or internal single post reviews. Single posts have the featured image, post content and ratings, and links to related posts in the same category.

Maddos is a WordPress theme so this guide assumes you have a basic understanding of WordPress.

Download the Maddos theme zip file to your computer.
From the WordPress admin menu, select Appearance -> Themes -> Add New.
Click on the Upload Theme button at the top.
Select the Maddos Theme zip file you downloaded and click Install Now.
Enter the server's FTP details to upload and install the zip file.
After sucessfully uploading, click on Activate Theme.
Install required plugins and any optional plugins you wish to use.
- Advanced Custom Fields (Required) - Adds Maddos specific custom fields to posts and categories.
- Maddos Theme Extensions (Required) - Adds Maddos specific custom functions for ACF fields and the custom Maddos Widget.
- Classic Editor (recommended) - The default Gutenberg editor saves post data in the background without updating the post page with the custom Maddos data (site icon, screenshot, etc.) Use the classic editor instead!
- Menu Icons (optional) - Use this plugin for adding icons to your menus. Nifty.
- Taxonomy Terms Order (optional) - Allows you to set a custom order for the categories in the Maddos Widget.
- User Submitted Posts (optional) - An easy way for visitors to submit sites to possibly be added to the directory. Set the Custom Field to 'Display and Require' and the Custom Field Name to 'website_url' in this plugin's settings.
- Widget Options (optional) - Tell your widgets where, when, and how to display on your site.
- WP Posts Carousel (optional) - Use the Owl carousel in header or footer widget to display posts by their featured images.
- WP-PostRatings (optional) - Allows users to vote on posts.
- WP-PostViews (optional) - Counts number of views for posts.
IMPORTANT! If you do not install the required plugins the theme will not display correctly.
You may now access theme settings in WordPress admin menu Appearance -> Maddos Settings.
You may now access the Maddos Widget in WordPress admin menu Appearance -> Widgets.
*** Also be sure to enter your License information for theme usage and automatic theme updates. ***
IMPORTANT! Maddos theme will not work properly without a valid license.

On theme activation, Maddos will create a Homepage Directory, using the Directory page template, and set it as your front page automatically. A blog page will be created as well, if you wish to link to it somewhere on your site. It should look like this:

Now we are ready to add content! Recommended order:

Adding Categories - The directory page needs to know which categories to display.
Adding Posts - Add some content to those categories to fill them out.
Adding Widgets - Use the Maddos Widget to layout categories and posts in different widget areas.
Theme Options - Once you have some content, play with the settings for colors, fonts, etc.

Please read if upgrading from a version earlier than 2.6

You must install the required plugin Maddos Theme Extensions to use the Maddos Post Metabox and Maddos Widget.
Maddos theme versions 2.6 and newer use a widgetized Directory page to display posts by category. The new Maddos Widget replaces many of the Maddos Settings, including all of the Directory Options. Currently, the deprecated Maddos Settings are still supported, and will still be used if the new Directory Column widget areas are empty. However you are encouraged to upgrade to the new widgetized format as it has much more flexibility and features. Soon these deprecated settings will be removed entirely.
If you are showing Archive pages with the grid format, I suggest regenerating thumbnails. The current version will ensure all those thumb sizes are the same.
The plugin Intuitive Custom Post Order does not seem to work within the WordPress Widget page and hasn't been updated in over a year. I now recommend using the plugin Taxonomy Terms Order instead.
If you are ordering posts by Alexa Rank, note that sites without a Ranking will not display until the next Alexa check is run (every 24 hours).

WordPress categories - The Advanced Custom Fields plugin adds two custom fields to entries in Posts -> Categories. Both are optional.

Category Icon - Will be shown on a directory page to the left of the category title. Can be a URL to an image (should be 24x24 in size) or html code such as a Font Awesome icon.
Example1: <i class="fa fa-asterisk"></i>
Example2: http://domain.com/wp-content/uploads/some_icon.png

Category Height - Will set a max pixel limit the Category container on a directory page, showing a scrollbar if the pixel size is greater.

After creating your categories, you can use the Maddos Widget to add them to your Directory Pages.

At the bottom of the post page you will see the Maddos custom metabox.

Site Url - The external link for the post is where we want to send the visitor interested in this entry. If Site Url is blank, the link will be directly to the post permalink. Maddos will automatically try to follow cloaked links or redirects (up to 10) to find the actual landing page to use for Auto Detect info. Site Url is also used to determine Alexa Rankings when the post is saved and on a daily basis.

Options - This overrides all other group settings, such as Maddos Widget or Post Options.

Open all Site Urls links in new tab - Opens site url link for this individual post in a new tab, regardless of Maddos Widget settings or Post Options. All new tab links will have the noopener attribute.
No Follow all Site Url links - Site url links for this individual post will get the nofollow attribute, regardless of Maddos Widget settings or Post Options.
Exclude this post from all Directory Pages - Post will still appear in all other pages such as search results and category pages.

Auto Detect - If checked, Maddos will use the Site Url and try to automatically fill in the checked field values (if they're not already set) whenever the post is saved.

Auto Detect Site Icon - Maddos will use the Google favicons service and import the PNG into the media library and set the Site Icon field automatically. If the site does not use a favicon, Google returns a default globe icon.
Auto Detect Mobile Friendliness - Maddos will use the Google PageSpeed API to determine if the Site Url gets a passing mobile friendly score. This can take a few seconds for Google to test.
Auto Detect Screenshot - Maddos will use the WordPress.com mShot service to generate a screenshot of the Site Url and set it as the featured image. Maddos gives mShots at least 10 seconds to generate the preview before importing. Depending on how busy the queue is, mShots may sometimes return a "Generating Preview" image - just remove the featured image and try saving the post again. If you don't like the screenshot returned by mShots, either wait for their cache to clear (unknown) or manually create your own image. If you want to see what image mShots is returning in your browser, enter https://s.wordpress.com/mshots/v1/http://www.[DOMAIN].com/ into your browser url field.

* NOTE * If you are using the Gutenberg editor it saves all information in the background and will not update the page to show you the content fetched above. Using the Classic Editor is recommended instead.

Site Icon - Will be displayed on the Directory page, and can be a URL to an image or html code such as a Font Awesome icon.

Mobile Friendly - If checked a mobile friendly icon will be displayed on the Directory page for this post.

Additional Icon - Can be a URL to an image or html code such as a country flag icon or a Font Awesome icon such as <i class="fa fa-asterisk"></i> or anything you wish. This will appear after the post title on a Directory page.

The post body

Maddos will display the featured image in the left column and the post content will be in the right. You can optionally use the keyword  to put the content after the split into it's own row. Example:

The Maddos Directory Widget was designed to be used in any of the 4 Directory Column Areas in the Appearance -> Widgets page. Each widget can display posts from multiple categories in the Maddos Directory style.

The Maddos Widget was coded before Gutenberg blocks, so please use the plugin Classic Widgets for now.

Title - You can give a name to the Maddos Directory widget for better organization. The title is only used in the admin widget page.

Categories - A unique Directory content box will be created for each category selected, displaying posts from that category. Group categories as you wish into separate widgets if you wish to display categories in a custom order.

CSS class - You can give these content boxes a class name for individual CSS styling.

Max Category Height - If set and the content box has a greater height than the max, a scroll bar will be added automatically.

Show Open/Close icon? This icon will collapse or display the content within the content box.

Show Descriptions? WordPress allows descriptions for each category, and you can choose to display them at the top of the content box.

Link Title to Page? - If you wish the category title to link to the category page or any other page. Useful for sub-Directory pages.

Order Posts By - How to order the posts in each category. In addition to standard WordPress options, it also includes the Maddos only option to order posts by their alexaRank.The alexaRank is determined when the post is first saved then on a daily basis. NOTE! If using a custom post order plugin to manually order posts, choose to Order Posts By 'none' so your custom order isn't overwritten.

Order Posts Direction - Depending on the order by selected, ASC (A-Z, 0-9, new to old) or DESC (Z-A, 9-0, old to new).

Max Posts to Show - Will show this many posts per category. If there are still more posts, the bottom of the widget will display 'See X More Sites'.

Link See X More Sites to Page? - If you wish the 'See X More Sites' to link to the category page or any other page. Useful for sub-Directory pages.

Link Post to - Link the posts to the Site Url (set in the post's custom Maddos metabox) or the post's permalink url.

New Tab - Open post links in a new tab. If set, the link will automatically have the 'noopener' rel tag.

No Follow - Post links will get the nofollow attribute.

Show Site Icon - Show the Site Icon (set in the post's custom Maddos metabox) next to each post.

Show Sticky Icon - Show a star icon next to sticky posts.

Show Additional Icon - Show the Additional Icon (set in the post's custom Maddos metabox) next to each post.

Show Mobile Icon - Show the Mobile Icon (set in the post's custom Maddos metabox) next to each post.

Show New Icon - Show the 'new' icon for posts less than 3 days old.

Show Review Icon on hover - Show the review icon next to each post when hovering the mouse over the post link, if the post content is not empty.

Show Thumbnail Icon on hover - Show the featured image when hovering the mouse over the post link.

Show Alexa Ranking - Show the alexa rank after the post title. Recommend using only if ordering by Alexa Rank.

Days to show New Icon - Posts younger than this number of days will display the New Icon.

Days to store Alexa position - If ordering posts by Alexa Rank, you can use this option to store the positions of the post results. If the post positions change during this time because of changes in Alexa Ratings, Maddos will show an up or down chevron showing the change in position.

You may also use any other widgets anywhere in each column, from any WordPress default widget to any other customized widget or create your own for ads, text, or toplists.

Example for Medium devices breakpoint of 992px:

Layout when device width is >= 992px

Layout when device width is < 992px

Google Fonts has over 700 fonts you can load and use on your site.

See Adding a Directory Widget

If you are unfamiliar with CSS, check out some CSS tutorials first.

To get the CSS class for any object on any site, right click on it in your browser and select Inspect Element. This will open a dialog box with the html code for that element.

For instance, if you did not wish to display the open folder icon in single posts, you would inspect the element and see that it's class is "glyphicon glyphicon-folder-open". So you would add this code to the custom CSS:

.glyphicon-folder-open { display: none; }

The Maddos theme uses these 3rd party JavaScript packages:

mwheelIntent - mwheelIntend tries to determine the users intent, to make the mousewheel event more usable.

Maddos can display a site icon for each post entry on a directory page. If there are many posts this can mean many seperate server requests when the page is loaded. To improve load time, you may wish to combine these site icons into a single image and use CSS Sprites instead.

Unfortunately there is no easy, automated way to do this, so here are some steps to help you do this manually, after you have entered most if not all of your content.

Download all the site icons that use an image into a local folder.
Upload all those images to a website like Instant Sprite.
In this example, I've uploaded 2 site icons.
Right-click the Sprite image, save it to your computer, and upload it to your site's root directory.
Copy/paste the first box in the Usage section to the Maddos Settings -> Custom CSS box.
Change the .sprite CSS background:url to match the location where you uploaded the sprite image.
Add the line .sprite { float:left; margin-top: 4px; } .
It should now look like this example screenshot of Appearance->Maddos Settings->Custom CSS:
Now for each of the <div> entries, copy/paste that code to the corresponding post's Site Icon, replacing the image url with the CSS code. Example:
Maddos will now load the Sprite image and display the Site Icons based on the CSS code.

How can I further customize the theme?
Can I make multiple Directory pages?
How can I change the site review icon, mobile friendly icon, or new icon?
Can I import data from a text file into the theme?
Can I display Alexa Ranking info on single posts?
Can I exclude certain sites from using Alexa Ranking info?
Can I use this with a tradescript?
Can I link the review to something other than the site_url or post?
Can I hide the legend icons on the Directory page?
Can I customize the 'Click Here' text link?
How can I modify the size of the scrollbar on the review page?
Maddos is not following the redirects of the Site URL to get Alexa info, screenshot, etc.
How to remove the post description on Archives pages using grid?
How to always show the Site Review icon, not just on mouse hover?
How can I have different grid/list archive layouts by category?
Can I customize the output for posts in the Directory?

How can I further customize the theme?

To customize a theme layout, you can use a plugin like Code Snippets to hook into the code and change things, and/or you can create a child theme for Maddos so you can edit files directly. With WordPress, any files found in the child theme will be used in place of the parent theme, with the exception of the functions.php file, which is loaded in addition to the parent theme's function.php file. Under no circumstances should you edit files in the parent directory, as they will be automatically overwritten when the theme is updated.

Example: to make custom changes to the header, you would copy the Maddos header.php file into the child theme's directory and make your changes to that file. WordPress will use the child theme's header.php file instead of the parent theme's header.php file, and updates to the parent theme will not overwrite your child theme changes.

If you don't know how to create a child theme, you can download a child theme for Maddos here.
Can I make multiple Directory pages?

Yes you can make as many Directory pages as you wish. They will all use the Directory Column Areas on the Appearance -> Customize -> Widgets page. You can specify which widgets appear on which pages and which conditions with the plugin Widget Context.
How can I change the site review icon, mobile friendly icon, or new icon?

These icons use the CSS background image attribute so all you need to do is override the CSS with the url for your replacement icon. If you have an image file, converting it to base64 data is highly recommended to reduce the number of hits when loading a directory page. You can convert it to base64 easily, then copy the CSS Background section and insert as Custom CSS for the proper class element in the Maddos Theme.

Screenshot from base64css.com:

Custom CSS Examples:
- To replace the site review icon:
```
.maddos-site-review-icon { background-image: url("data:image/png;base64,iVBORw0KG...[SNIPPED]"); }
```
- To replace the mobile friendly icon:
```
.maddos-mobile-friendly-icon { background-image: url("data:image/png;base64,iVBORw0KG...[SNIPPED]"); }
```
- To replace the 'new' icon:
```
.maddos-new-icon { background-image: url("data:image/png;base64,iVBORw0KG...[SNIPPED]"); }
```
Can I import data from a text file into the theme?
You can use a CSV Importer plugin to create posts. However the Maddos auto detect functionality will not be triggered. You'd have to save each imported post manually if you want Maddos to auto detect the Site Icon, Mobile Friendliness, and/or a Screenshot.

Can I display Alexa Ranking info on single posts?

Yes, here are some sample uses of Alexa Ranking info:

To show the site's Alexa Rank on the single post page after the content, you can use the code snippet


function maddos_show_alexa_single( $content ) {
  $post_id = get_the_ID();
  if ( is_single() && $post_id ) {
	$rank = get_post_meta( $post_id, 'alexaRank', true );
	$content .= $rank ? "<p>Alexa Rank: " . $rank . "</p>" : '';
  }
  return $content;
}

Can I exclude certain sites from using Alexa Ranking info?

Yes. This can be useful if you have some Site Url entries on well known sites (wikipedia.org, reddit.com, etc) and you don't want those high ranking sites to have precedence, you can use a filter to exclude them from getting their daily Alexa Ranking. If you are ordering your directory by Alexa Ranking, sites without an alexa ranking value will appear after those that do,ordered by date.
```
add_filter( 'maddos_alexa_exclusions', 'maddos_alexa_exclusions' );

function maddos_alexa_exclusions( $excludes ) {
  $excludes = array(
	'wikipedia.org',
	'reddit.com'
	);
  return $excludes;
}
```
Can I use this with a tradescript?

Yes, you can specify a tradescript url as the Site Url for each post, but a better option would be use a filter hook to display the tradescript url automatically. For example, if your trade script uses /tx/out.php?t=theurl you could use this Code Snippet to modify the Site Url before it is displayed:
```
add_filter( 'maddos_get_site_url', 'maddos_tx_tradescript' );

function maddos_tx_tradescript( $url ) { 
  return "/tx/out.php?t=" . $url;
}
```
Can I link the review icon to something other than the site_url or post?

Yes you can use a filter hook to swap the link out for anything you like. In this example, you can save a custom field in a post named 'offsite_url' :

Then add a small code snippet that will swap out the offsite_url for the site_url if it exists:
```
add_filter( 'maddos_get_site_url', 'change_site_url' );

function change_site_url( $site_url ) {
  $offsite_url = get_post_meta( get_the_ID(), 'offsite_url', true );
  return ! empty( $offsite_url ) ? $offsite_url : $site_url;
}
```
Can I hide the legend icons on the Directory page?

Yes just use this custom CSS:
```
.maddos-legend { display: none; }
```

Can I customize the 'Click Here' text link?

Yes you can use custom CSS to change any element. Example:


.maddos-post-linktext { color: #fff; background: #53ad51; padding: 14px 0; border-radius: 5px; margin-top: 10px; }
.maddos-post-linktext:visited { color: #fff; }
.maddos-post-linktext:hover { background: #439d41; }

How can I modify the size of the scrollbar on the review page?

You may need to adjust the size of the review scrollbar depending on the size of your screenshot. To do so, use custom CSS. Example:
```
.maddos-content-scroll { max-height: 460px; }
@media (max-width: 1200px) { .maddos-content-scroll { max-height: 360px !important; } }
```
Maddos is not following the redirects of the Site URL to get Alexa info, screenshot, etc.

WordPress will automatically follow redirects made using standard HTTP status codes 3xx. Maddos will also try to recognize sites using the Meta Refresh header to redirect. Any sites using other redirect methods will not be recognized. If one of the urls uses a non-standard redirect that is not recognized, you can instead hook in and force Maddos to use the final url. Here is an example code snippet:
```
add_filter( 'maddos_site_url_check', 'modify_maddos_site_url_check' );

function modify_maddos_site_url_check( $link ) {
  if ( $link === 'https://web101best.com/go_cloudways')
	return 'https://www.cloudways.com/en/';
  else if ( $link === 'https://web101best.com/go_duda' )
	return 'https://www.duda.co/';
  return $link;
}
```
How to remove the post description on Archives pages using grid?

You can change ANY element you want with Appearance -> Maddos Settings -> Custom CSS. You would probably want to hide the post descriptions if you don't use them. If you right click on the description element on the grid page, you'll see the class name is maddos-grid-container p. So here is how you would hide the post description on grid pages with custom CSS .maddos-grid-container p { display:none; }.

Grid layout with empty post content:

Use Custom CSS to hide the description element:
.maddos-grid-container p { display:none; }
How to always show the Site Review icon, not just on mouse hover?

You can change ANY element you want with Appearance -> Maddos Settings -> Custom CSS. If you right click on the description element on the grid page, you'll see the class name is maddos-review. So here is how you would always show the site review icon with custom CSS .maddos-review { display:block !important; } (we need to use the important tag so that the javascript triggered on mouse hover doesn't toggle the status).

REMINDER: The site review icon is only available if the post content is not empty.

Category posts with site review icon on hover:

Use Custom CSS to always show the site review icon:
.maddos-review { display:block !important; }

How can I have different grid/list archive layouts by category?

The global archive layout setting applies to all archive pages, but you can customize by category however you like using the Maddos filter hook 'maddos_archive_layout'. Here is an example code snippet:


add_filter( 'maddos_archive_layout', 'change_maddos_archive_layout', 10, 1 );

function change_maddos_archive_layout( $layout ) {
   // see https://developer.wordpress.org/reference/functions/is_category/
   if ( is_category( 'abc' ) ) {
      return 'grid';
   }
   else if ( is_category( 'xyz' ) ) {
      return 'list';
   }
   // otherwise return global layout setting for archives
   return $layout;
}

Can I customize the output for posts in the Directory?

Yes you can use a code snippet to modify the default output line:


add_filter( 'maddos_category_post_output', 'maddos_custom_output', 10, 3 );

function maddos_custom_output( $default, $post_id, $vars ) {
	$custom_output = sprintf( '%s %s <a class="maddos-link" title="%s" %s %s href="%s">%s %s %s %s %s %s %s</a> %s', 
				 $vars['site_icon'], 		// Site Icon from Maddos metabox
				 $vars['alexa_chevron'], 	// arrow-up, arrow-down or empty
				 $vars['title'], 		// post title for anchor link
				 $vars['target'], 		// target="_blank" or empty
				 $vars['rel'], 			// rel="nofollow/noopener" or empty
				 $vars['href'], 		// Site Url from Maddos metabox
				 $vars['title'], 		// post title for display
				 $vars['sticky_icon'], 		// if sticky post
				 $vars['additional_icon'], 	// Additional Icon from Maddos metabox
				 $vars['mobile_icon'], 		// set if Mobile Friendly is checked
				 $vars['new_icon'], 		// set if posts < New Days in widget
				 $vars['alexa_rating'], 	// alexa rating number
				 $vars['hover_thumb'], 		// thumbnail image on hover if checked
				 $vars['review_icon'] 		// if checked in widget and post has content
				);
	return $custom_output;
}

Maddos Theme for WordPress

Installation

Theme Setup

Upgrading old version

Please read if upgrading from a version earlier than 2.6

Adding a Category

Adding a Post

The post body

Adding a Directory Widget

Maddos Settings -> General Options

Maddos Settings -> Header Options

Maddos Settings -> Menu Options

Maddos Settings -> Directory Options

Maddos Settings -> Archive Options

Maddos Settings -> Post Options

Maddos Settings -> Footer Options

Maddos Settings -> Custom CSS

Maddos Settings -> License

JavaScript

Sprites

FAQ

Maddos Theme for WordPress

Installation

Theme Setup

Upgrading old version

Please read if upgrading from a version earlier than 2.6

Adding a Category

Adding a Post

The post body

Adding a Directory Widget

Maddos Settings -> General Options

Maddos Settings -> Header Options

Maddos Settings -> Menu Options

Maddos Settings -> Directory Options

Maddos Settings -> Archive Options

Maddos Settings -> Post Options

Maddos Settings -> Related Post Options

Maddos Settings -> Footer Options

Maddos Settings -> Custom CSS

Maddos Settings -> License

JavaScript

Sprites

FAQ