93Digital Backend Documentation

OOP theming oriented developer guide.

Introduction

The scope of this document is to explain how to properly use all the classes and methods used in theme and plugin development for developers. All the methods described below are used regularly on theme development. This OOP approach has been taken to improve the development and the maintenance of the themes and also to avoid write the logic on the templates as much as you can.

Feel free to add or modify any of the methods described here but if you do that, please keep this documentation updated with all the changes made.

In order to maintain consistency between the projects please document and add the necessary comments in every method you add. Every method is documented with the following structure :

  • Description : Short description. You should figure out what the method does at glance, so not more than 1 or 2 lines are recommended.
  • Params : Params accepted by the method. You must provide the type of the parameter (lowercase for primitive types), name, description and you must specify wheter the parameter is required or not.
  • Return : Return value must be specified following the structure explained above.

Method Example:

              

/**
*
* Method description
*
* @param String (required) $param_1 Param 1 description
* @param int $param_2 Param 2 description
* @return Array $status Return value description
*/
public static function method_name($param_1, $param_2 = null){
                      
  //variables
  $status = array();

  //Logic goes here

  return $status ;  

}

              
            

Classes

These are the custom classes that we are using on our theme development:

Utilities

Utilities is a class designed to provide all the data required to display things on the screen. Layouts, dynamic css classes, menus , post featured image url and other stuff related with dynamic load of the page are coming from the Utilities methods.

Location : theme_folder/inc/class/utilities.php

Data

Data is a class designed to provide all the data related with any wp feature on the template. Custom fields data and other post/page/category/term data related with it should be parsed and provided by the data method called at the top of the template.

Location : theme_folder/inc/class/data.php

The scope of all this methods are the whole theme as they are included on functions.php.

All the methods are public and static so you dont need to create an object to use them.

By convention, all the method's names must by writen using underscores to separate different words on the name. (This is not applied on Kantox code)

Utilities

display_layout_items()

This method works with ACF puigin and the flexible content field. Basically you pass the flexible content field name and the current page ID and this method displays all the layouts on the page.

Code Example:

                 

/**
*
* This method displays layout content blocks. 
* Call this method in a template to display the layout 
* blocks
*
* @param String (required) $field_name ACF field name
* @param int (required) $page_id Current page id
*/
public static function display_layout_items($field_name, $page_id){

  //variables
  global $layout, $current_page_id;
  $current_page_id = $page_id;
  $items = get_field($field_name, $page_id);


  if(is_array($items)){

    foreach($items as $layout){

      $layout_name = $layout['acf_fc_layout'];

      get_template_part('template-parts/layout', $layout_name);

    }//end foreach

  }//end if
                        

}

                 
               

first_time_cookie()

Generally this method should be used to check and display the message about cookie usage. It accepts the cookie time as a parameter. This method creates the cookie and returns false after that. Otherwise it returns true.

Code Example:

                 
/**
  *
  * This method checks if the first time cookie exists. If does not, it is created on the client browser
  *
  * @param int $time Cookie expired time in seconds
  * @return Object $cookie Object which contains the cookie status and the link to the privacy policy page in each language
  */
  public static function first_time_cookie($time = 2678400){

    //variables
    $cookie = new stdClass();
    $cookie->status = false;

    //setting cookie if it does not exist
    if(!isset($_COOKIE['first']) || !$_COOKIE['first'])
      setcookie('first', true, time()+$time);
    else
      $cookie->status = true;

    //getting privacy policy permalink
    $page_id = Data::get_external_page_id('privacy policy');
    $cookie->permalink = get_permalink($page_id);


    return $cookie;
  }
  

                 
               

get_post_featured_image_url()

This method retuns the post featured image url. It accepts the id of the post and the size as a parameters.

Code Example:

                 
/**
  *
  * Gets the post featured image url
  *
  * @param int (required) $post_id ID of the post that we want to retrieve the attached feature image
  * @param String $size Image size
  * @return String $image_url Featured image url. Empty if the post has not any image attached
  */
  public static function get_post_featured_image_url($post_id, $size = 'medium'){

    //variables
    $image_url = '';

    //getting attachment image url
    if(has_post_thumbnail( $post_id )){
      $image_id = get_post_thumbnail_id( $post_id );
      $image = wp_get_attachment_image_src($image_id, $size, true );
      $image_url = $image[0];
    }

    return $image_url;
  }
  

                 
               

get_object()

This method casts an array into an object.

Code Example:

                 
  /**
  *
  * This function gets an object based on a array
  *
  * @param Array (required) $array Array to be converted
  * @return Object
  */
  public static function get_object($array){
    return (object) $array;
  }
  

                 
               

register_custom_post()

This method allows you to create a new custom post. The slug, dashicon , archve type, taxonomies type , supports array and the name can be passed as a parameters, being the slug and the icon mandatories.

Code Example:

                 
  /**
  *
  * Register custom post
  *
  * @param String (requried) $name Custom Post Identifier name
  *
  */
  public static function register_custom_post( $slug, $icon, $archive = false, $taxonomies = true, $supports = array('title','thumbnail'), $name = null ) {
    $args = array(
      'label' => ucfirst( preg_replace( '/[-_]/', ' ', $slug ) ),
      'public'          => true,
      'menu_position'       => 5,
      'supports'          => $supports,
      'has_archive'       => $archive,
      'menu_icon'         => $icon,
      'show_ui'         => true,
      'rewrite'         => array('slug' => $slug),
      'hierarchical'        => false,
      'show_in_nav_menus'     => true
    );

    if( null == $name ) $name = str_replace( '-', '', $slug );
    register_post_type(self::THEME_PREFIX . '_' . $name, $args);
  }
  

                 
               

register_taxonomy()

This method allows you to register a new custom taxonomy. The label, slug and taxonomy name are required parameters. The name parameter is the name of the custom post related with the new taxonomy.

Code Example:

                 
/**
  *
  * This method registers a new taxonomy
  *
  * @param String (required) $label Taxonomy label
  * @param String (required) $slug Taxonomy slug
  * @param String (required) $name Custom post name. This taxonomy will be added to the custom post name provided.
  */
  public static function register_taxonomy( $label, $slug, $name ) {
      $args = array(
        'hierarchical'      => true,
        'label'             => $label,
        'show_ui'           => true,
        'show_admin_column' => true,
        'query_var'         => true,
        'rewrite'           => array( 'slug' => $slug ),
      );

      register_taxonomy($slug, array(self::THEME_PREFIX . '_' . $name), $args);
    }
}
  

                 
               

crop_text()

This method crops large texts or paragraph. By default the text lenght is 50 characteres and an ellipsis is added at the end of the string. Both text lenght and appended text can be changed passing them as a parameteres. This method returns the cropped text ready to be displayed.

Code Example:

                 
/**
  *
  * This method crops text to the specified lenght
  *
  * @param String (required) $the_string Text to be cropped
  * @param int $max_lenght Number of characteres displayed on the text. 50 by default.
  * @param String $append Text to be appended at the end of the cropped string. Suspension points by default.
  * @return String $cropped Text cropped
  */
  public static function crop_text($the_string, $max_lenght = 50, $append = null){

    //variables
    $cropped = $the_string;

    if(!is_int($max_lenght))
      $max_lenght = 50;

    if(is_null($append) || !is_string($append))
      $append = '...';

    if(strlen($the_string) > $max_lenght){
      $tem_string = substr($the_string, 0, $max_lenght);
      $cropped = $tem_string . $append;
    }

    return $cropped;

  }
  

                 
               

get_array()

This method casts an object into an array. It is the opposite to get_object(). An object has to be passed as a parameter an it returns an array.

Code Example:

                 
/**
  *
  * This method casts an object into an array
  *
  * @param Object (required) Object to be converted
  * @return Array
  */
  public static function get_array($object){
    return json_decode(json_encode($object), true);
  }
  

                 
               

check_user_logged_in()

This method checks if the current user is logged in. You can pass the pagen name where the user is redirected if they try to open a required logged in page.

Code Example:

                 
  /**
  *
  * This method checks if the user is logged in
  *
  * @param String $homepage Home page name. 'Home' by default
  * @return void
  */
  public static function check_user_logged_in($homepage = 'Home'){

    //variables
    $page_permalink = Data::get_pagelink_by_name($homepage);

    //redirect user to home if is not logged in
    if(!is_user_logged_in()){
      wp_safe_redirect($page_permalink );
      exit();
    }

  }
  

                 
               

safe_redirect()

This method performs a safe redirect. This is a wrapper of wp_safe_redirect. User is redirecter to the homepage by default but you can pass the name of any other page as a parameter. This method uses the Data::get_pagelink_by_name method, so make sure you have that method on the proper class before copy this one.

Code Example:

                 
   /**
   *
   * This function performs a safe redirect. It is a wrap of the wp_safe_redirect function. It accepts a page name as a parameter
   *
   * @param String $pagename
   */
   public static function safe_redirect($pagename = null){

    //varibles
    $url = (is_null($pagename) || !is_string($pagename)) ? get_home_url() : Data::get_pagelink_by_name($pagename);

    //redirecting user
    wp_safe_redirect($url);
    exit();
    
   }
  

                 
               

get_post_filtered_content()

This method allows you to display the post content filtered as you do with the_content() but in any part of the theme. You need to pass the post id as a parameter.

Code Example:

                 
   
  /**
  *
  * This method returns the post content out of the loop properly filter
  *
  * @param int (required) $post_id
  * @return String $content
  */
  public static function get_post_filtered_content($post_id){

    //variables
    $content = '';

    //getting post data
    $the_post = get_post($post_id);

    //getting raw contentn
    $content = $the_post->post_content;

    //applying filters
    $content = apply_filters( 'the_content', $content );
    $content = str_replace(']]>', ']]>', $content);

    return $content;

  }

                 
               

get_ajax_data()

This method returns the minimun data that you need to send in an ajax request. It returns the admin ajax url and you can pass a nonce as a parameter.

Code Example:

                 
   
  /**
  *
  * This method returns an object with all the neccesary ajax stuff
  *
  * @param String $nonce Nonce that will be checked on the process function with PHP
  * @return Object $ajax_data
  */
  public static function get_ajax_data($nonce = null){

    //variables
    $ajax_data = new stdClass();

    //getting ajax url
    $ajax_data->url = admin_url('admin-ajax.php');

    //getting nonce
    $ajax_data->nonce = (!is_null($nonce)) ? wp_create_nonce($nonce) : 'no_nonce';

    return $ajax_data;

  }

                 
               

get_process_form_data()

Similar to get_ajax_data(), this method returns the admin url to process a form. Optionally you can pass the nonce and the form method as a parameter.

Code Example:

                 
   
  /**
  *
  * This method returns an object with all the data that you need to send and process a form with WP
  *
  * @param String (required) $nonce Nonce's name
  * @param String $method Form method. Post by default
  * @return Object $form_data
  */
  public static function get_process_form_data($nonce, $method = null){

    //variables
    $form_data = new stdClass();

    //getting admin url
    $form_data->admin_url = admin_url('admin-post.php');

    //getting the method to send the data
    $form_data->method = (is_null($method)) ? 'post' : $method;

    //getting nonce
    $form_data->nonce = wp_create_nonce($nonce);

    return $form_data;


  }

                 
               

check_nonce()

This method wraps the wp_verify_nonce function, but this one only return true or false. The nonce name and the nonce value has to be passed as a parameter.

Code Example:

                 
   
  /**
  *
  * This method checks a wp nonce
  *
  * @param String | int | boolean (required) $nonce_value
  * @param String (required) $nonce_name
  * @return boolean $status
  */
  public static function check_nonce($nonce_name, $nonce_value){

    //checking nonce
    $status = (wp_verify_nonce( $nonce_name, $nonce_value ) ) ? true : false;
    return $status;

  }

                 
               

Data

display_template_parts()

This method displays all the template parts inside a template. It is very useful when the theme is developed (or partly developed) using ACF relational fields.

Code Example:

                 
 /**
  *
  * This method displays all the template parts of a template
  *
  */
  public static function display_template_parts(){

    //displaying block layouts
    $items = get_field('layout');

    if(is_array($items)){

      foreach($items as $layout){

        $layout_name = $layout['acf_fc_layout'];

        get_template_part('template-parts/layout', $layout_name);
      }
    }

  } 
  

                 
               

get_default_avatar_url()

This method returns the default avatar image url. Very useful when you need to display a default avatar for some user, etc.

Code Example:

                 
  /**
  *
  * This method returns the default avatar image url
  *
  * @return String $default_avatar_url Default avatar url
  */
  public static function get_default_avatar_url(){

    //variables
    $default_avatar_url = '';

    $args = array(
      'default' => 'mystery',
      'force_default' => true
    );

    $default_avatar_url = get_avatar_url(3, $args);

    return $default_avatar_url;
  } 
  

                 
               

get_social_media()

This method returns an object with all the social media urls defined and setted on the current theme. The code example below may vary depending of the theme.

Code Example:

                 
  /**
  *
  * This method returns the social media data
  *
  * @return Object $social_media Social media links
  */
  public static function get_social_media(){

    //variables
    $social_media = new stdClass();

    //getting social media data
    $social_media->facebook = nine3_setting( 'facebook' );
    $social_media->google = nine3_setting( 'google-plus' );
    $social_media->twitter = nine3_setting( 'twitter' );
    $social_media->linkedin = nine3_setting( 'linkedin' );
    $social_media->youtube = nine3_setting( 'youtube' );

    return $social_media;


  }
  

                 
               

display_sidebar_templates()

This method returns all the tempates assigned to a sidebar. This is very useful with themes developed (or partly developed) using ACF realtional fields

Code Example:

                 
  /**
  *
  * This method displays all the main sidebar child templates
  *
  * @return void
  */
  public static function display_sidebar_templates(){

    //variables
    $items = get_field('sidebar_layout');

    if(is_array($items)){

      foreach($items as $layout){

        $layout_name = $layout['acf_fc_layout'];

        //displaying block layouts
        get_template_part('template-parts/layout', $layout_name);

      }//end foreach

    }//end if
  }
  

                 
               

get_author_data()

This method returns all the author data based on a post id, which is a required parameter. The code of the example provided below may change depending of the theme.

Code Example:

                 
  /**
  *
  * This method gets all the author data based on the post id provided as a parameter
  *
  * @param int (required) $author_id
  * @return Object $author_data Post author data
  */
  public static function get_author_data($author_id){

    //variables
    $author_data = new stdClass();
    $parse_id = 'user_' . $author_id;

    //getting the author data
    $data = get_userdata($author_id);

    //getting name
    $author_data->name = ucfirst($data->display_name);

    //getting email
    $author_data->email = $data->user_email;

    //getting profile pic
    $author_data->gravatar_url = get_avatar_url($author_id);

    return $author_data;

  }
  

                 
               

get_archive_data()

This method returns an object with the id and the name of a category. This method has to be used only on the archive page (archive.php)

Code Example:

                 
  /**
  *
  * This method returns the category data. Has to be used in archive page (archive.php)
  *
  * @return Object $category_data
  */
  public static function get_archive_data(){

    //variables
    $category_data = new stdClass();

    //getting category id
    $category_data->id = get_query_var('cat');

    //getting category name
    $category_data->name = single_cat_title("", false);

    return $category_data;
  }
  

                 
               

get_tag_data()

This method returns an object with the id and the name of a tag or a custom taxonomy. This method has to be used either on the tag page (tag.php) or in a custom taxonomy template.

Code Example:

                 
  /**
  *
  * This method returns the tag data. Has to be used in tag page (tag.php)
  *
  * @return Object $tag_data
  */
  public static function get_tag_data(){

    //varibles
    $tag_data = new stdClass();

    //getting tag id
    $tag_data->id = get_query_var('tag_id' );

    //getting tag name
    $tag_data->name = single_tag_title('', false);

    return $tag_data;
  }  

                 
               

get_single_post_data()

This method returns an object with all the data related with a single post. This means that this data would be displayed on a single post page although this method can be useful in some other cases. The code example below may vary depending of the theme and the templates.

Code Example:

                 
  /**
  *
  * This method returns all the single post data ready to be displayed
  *
  * @param int (required) $post_id Current_post id
  * @param int (required) $author_id Current post author id
  * @return Object $post_data Object which contains all the post data ready to be displayed
  */
  public static function get_single_post_data($post_id, $author_id){

    //variables
    $post_data = new stdClass();
    $utils = new Utilities();

    //getting author data
    $post_data->author = self::get_author_data($author_id);

    //getting featured image
    $post_data->featured_image = $utils->get_post_featured_image($post_id);

    return $post_data;

  }  

                 
               

get_children_pages()

This method returns an object which contains all the child pages of a page. The name of that page has to be provided as a parameter.

Code Example:

                 
  /**
  *
  * This method returns all the child pages of a page by page name
  *
  * @param String (required) $page_id Page id
  * @param boolean $gch Wheter to display granchildren pages or not . Default : true
  * @return Object $children Children pages as an object
  */
  public static function get_children_pages($pagename, $gch = true){

    //variables
    $children = array();

    //getting page as an object
    $current_page = get_page_by_title($pagename);

    //set up the objects needed -- filter by grand children if gch is true
    $all_wp_pages = ($gch) ? get_pages() : get_pages('child_of='.$current_page->ID.'&sort_order=desc&parent='.$current_page->ID);

    //getting children pages
    $children = get_page_children( $current_page->ID, $all_wp_pages );

    //return children pages as an object
    return (object) $children;

  } 

                 
               

get_pagelink_by_name()

This method returns the page permalink by name. The name of the page has to be passed as a parameter. Notice that this method is using the get_external_page_id method so you need to include that method on your Data class to make this one works.

Code Example:

                 
  /**
  *
  * This method returns the page permalink based on the page name
  *
  * @param String $page_name (required) Page name whose permalink is displayed
  * @return String $page_permalink Cookie permalink
  */
  public static function get_pagelink_by_name($page_name){

    //variables
    $page_permalink = '';

    $page_id = self::getExternalPageID($page_name);

    $page_permalink = get_the_permalink($page_id);

    return $page_permalink;
  } 

                 
               

get_external_page_id()

This method returns the page id based on the page name. Very useful when you need to pull some data from other page out of a menu or loop context. The name of the page is a requered parameter.

Code Example:

                 
  /**
  *
  * This method returns the blog page id
  *
  * @return Int $blog_id
  */
  public static function get_external_page_id($pagename){

    //variables
    $page = get_page_by_title($pagename);

    return $page->ID;
  } 

                 
               

get_thum_alt_text()

This method returns the post featured image alternative text. This text is usuarlly displayed as the img tag alt attribute value. The post ID has to be passed as a parameter.

Code Example:

                 
 /**
  *
  *
  * This method returns the thumbnail post alt text
  *
  * @param int (required) $post_id Current post id
  * @return String $thum_alt Thum alt text
  */
  public static function get_thum_alt_text($post_id){

    //variables
    $thum_alt = 'No alt text available';

    //getting post data
    $post = get_post(get_post_thumbnail_id( $post_id ));

    //post_meta
    $post_alt = get_post_meta($post->ID, '_wp_attachment_image_alt', true);

    $thum_alt = ($post_alt !== '') ? $post_alt : $thum_alt;

    return $thum_alt;

  }

                 
               

get_post_excerpt()

This method returns the post excerpt ready to be displayed. This can be used out of the loop and you need to pass the post ID as a parameter.

Code Example:

                 
 /**
  *
  *
  * This method returs the post excerpt. It can be used out of the loop
  *
  * @param int (required) $post_id Post id
  * @return String $ouput Post excerpt
  */
  public static function get_post_excerpt($post_id){

    //variables
    global $post;

    $save_post = $post;
    $post = get_post($post_id);
    $output = get_the_excerpt();
    $post = $save_post;

    return $output;

  }