MAS:Related Scenes

The following tutorial shows how to set up a "Related Scenes" or "Other scenes you might like" feature on your gallery template. It is not a built-in feature, but a combination of front-end programming (all inside templates and/or external JavaScript file) plus special use of the MAS built-in search functions.

1. First you will need to create a content attribute (one or more) with keywords that will define the similarities or relations between scenes, and apply it to the content sets that will participate in this feature. Most sites already have such attributes, frequently named Keywords, or Tags, or Niches. For the purpose of this tutorial let's assume we have an attribute named SceneKeywords.

2. Then we need a section containing the search-results template - partial HTML code that makes the layout of the displayed “related” results. It must follow the rules for a standard search-results template, but without header/footer – just the piece of html for the row(s) with “related” results, using regular template tags. Note that it will be loaded with Ajax and not with php include in the main site scope, so if that template is calling any php functions usually defined in the header (e.g. ExplodeSearch() ) it will fail – those function definitions must be repeated, or included separately in this template. Here's a simple code that you can use to start with:

{loop#:1:5}<!-- start_link -->
<div class="my-update">
  <a href="[ahref#]">[name#]</a>
  <span class="th">
    <a href="[ahref#]"><img src="[imgsrc#]" alt="" /></a>
  </span>
<!-- end_link -->{/loop#}

3. In your site header or footer template, or directly inside the gallery template (but not in more than one place), define the following multi-purpose php helper function:

<?php
function SearchAttributes($list) {
	$list = str_replace(', ', ',', trim($list)); if (!$list) return false;
	if ($list == 'n/a') return $list;
	$ar_list = explode(',', $list);
	foreach ($ar_list as $key=>$value)  $ar_list[$key] = '%22' . urlencode(str_replace(' ','__',$value)) . '%22';
	$list = implode(',', $ar_list);
	return $list;
}
?>

4. In your gallery template, put the following piece of code at the location where you want the search results with related sets to be displayed.

<div id="related_scenes" data-src="<?=SearchAttributes('[attribute.scenekeywords]');?>" data-sid="35" data-ref="1" data-lid="[lid]" data-categories="3,6" data-minresults="5" data-similar="[title]" ><!-- Contents loaded with Ajax --></div>

Here's a detailed description of the properties used:

• id="related_scenes" - unique DOM element id that will be used in the next step, to let the jQuery/Ajax code load the results into this container

• data-src="<?=SearchAttributes('[attribute.scenekeywords]');?>" - this property and value must be given exactly this way, you can only change the name of the attribute containing the keywords to search similar results for, as defined in Step 1 above.

• data-sid="35" - the section ID of the template with search results, as defined in Step 2 above.

• data-ref="1" - the ID of any section within the current site, usually the Home or Header template (as in all MAS search forms/functions).

• data-lid="[lid]" - this property and value must be given exactly this way, it will tell MAS not to include the current content set in the displayed similar results.

• data-categories="3,6" - one category ID, or multiple comma-separated category id's where to search at. Optional, if not specified, the returned results will be from all categories.

• data-minresults="5" - the number of results you will be displaying, must be greater than or equal the number of tags (value of {loop} tag in the search template. Optional, default = 5.

• data-similar="[title]" - Optional. If used, it will let MAS look not only in the attribute SceneKeywords but also in content set titles to find results similar to the current one. Useful to display matching photo/video sets with the same title, or other titles from a series (since MAS will ignore numbers in the titles when doing this search).

5. You must have jQuery included in your site's header or footer templates. Most sites already have it. If you still don't, you can use the following code:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>

6. Your site may already have a $(document).ready(function() {... in its header/footer template (or external *.js file referenced in the header/footer). If yes, then add the code below to your function. Otherwise, put it in your header or footer template right under the call to jQuery script.

<script>
$().ready(function() {
 
 
	function masRelatedScenes() {
	  if (divRelated = $('#related_scenes')) {
	    var categories = divRelated.attr('data-categories'); categories = (categories ? '&categories=' + categories : '');
	    var minresults = divRelated.attr('data-minresults'); if (minresults < 1) minresults = 5;
	    var similar = divRelated.attr('data-similar'); similar = (similar ? '&similar_title=' + encodeURIComponent(similar) : '');
	    var srchUrl = 'search.php?sid=' + divRelated.attr('data-sid') + '&ref=' + divRelated.attr('data-ref') + categories + '&method=and/or&minresults=' + minresults + '&exclude=' + divRelated.attr('data-lid') + similar + '&q=' + divRelated.attr('data-src');
	    divRelated.load(srchUrl);
	  }
	}
	masRelatedScenes();
 
 
});
</script>

NOTE: Remember that the search results, including related scenes, are cached. While in development, to be able to see immediate action after changes to the results template, you should disable search caching in the local browser window. To do so, copy this URL into your browser after the members area URL (e.g. keep http://yoursite.com/members/ then paste)

search.php?nocache=on

then go back to the edited content page and refresh (F5) within the same browser window!