Advanced Sidebar Menu – Developer Docs

Advanced Sidebar Menu

Internationalization

This plugin has support for internationalization translations. However it does not come built in with the different languages. If you wish to help out by translating this plugin, you may find the .pot file in the languages folder of the plugin. Please send me your .mo translation files and I will add them to the plugin.

For now if you are familiar with using the ‘load_plugin_textdomain()’, hook you may use it with the domain ‘advanced-sidebar-menu’ to use your translations. Uploading a complete .mo file to the languages folder of the plugin will work the same way, however it will be deleted when you update the plugin unless you already sent it to me and I have added it.

 

Template Overrides

You may override the full output of the either widget by using a template override. In the plugins folder you will find a folder named views. The following files will be found there:

  1. category_list.php – category widget output
  2. page_list.php – page widget output
  3. sidebar-menu.css – built in css used when option is selected in widget

To use your own file, simply create a folder in you active theme named advanced-sidebar-menu. Copy any of the above named files into that folder and the plugin will automatically use your version of the file.

Filters List

Page Widget

advanced_sidebar_menu_after_widget_form
Runs at the end of the widget form within the admin. Used to add custom form fields to the widgets.
Accepts 2 arguments:
  1. The widget values.
  2. The complete widget object.
add_action('advanced_sidebar_menu_after_widget_form','custom_form_field', 10, 2);
function custom_form_field( $values, $class ){
       echo '<input type="text" name="custom" value="' . $values[ 'include_parent' ] . '" />';
}
advanced_sidebar_menu_page_widget_update
Runs during a widget save. Used to change values being saved in the widgets.
Accepts 2 arguments:
  1. The widget values.
  2. The old widget values.
add_action('advanced_sidebar_menu_page_widget_update','change_widget_values', 10, 2);
function change_widget_values( $new_values, $old_values ){
       $new_values[ 'exclude' ] = $old_values[ 'exclude' ];
       return $new_values;
}
advanced_sidebar_menu_excluded_pages
Filter the excludes pages during widget rendering. Used to exclude or force include pages for all widgets.
Accepts 5 arguments:
  1. The excluded pages.
  2. The current page.
  3. The widget arguments.
  4. The widget values.
  5. The full menu object.
add_action('advanced_sidebar_menu_excluded_pages','exclude_a_page', 10, 5);
function exclude_a_page( $excluded, $current_page, $widget_args, $widget_values, $menu_class ){
       $excluded[] = 5; //excludes page with id of 5
       return $excluded;
}
advanced_sidebar_menu_post_type
Filter the post type being used in the widgets. Used to allow the menu to use a custom post type other than page.
Accepts 4 arguments:
  1. The current post type (default ‘page’ ).
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_excluded_pages','change_post_type', 10, 4);
function change_post_type( $current_post_type, $widget_args, $widget_values, $menu_class ){
       $current_post_type = 'product';
       return $current_post_type;
}
advanced_sidebar_menu_proper_single
Filter  where the menu may be used. Used to allow rendering the menu on pages like home that are not a proper single page. Should be used in conjunction with the ‘advanced_sidebar_menu_top_parent’ filter.
Accepts 4 arguments:
  1. If this is a proper single page where the menu should display.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_proper_single','display_on_homepage', 10, 4);
function display_on_homepage( $is_displayed, $widget_args, $widget_values, $menu_class ){
       if( is_home() ) $is_displayed = true;
       return $is_displayed;
}
advanced_sidebar_menu_top_parent
Filter which page is used as the top parent. Used to allow specify the page to be used as the top level parent page, which the menu is built off of.
Accepts 4 arguments:
  1. The current top parent page.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_top_parent','custom_top_page', 10, 4);
function custom_top_page( $top_page_id, $widget_args, $widget_values, $menu_class ){
       $top_page_id = 2; //Sample page will always be top level page
       return $is_displayed;
}
advanced_sidebar_menu_order_by
Filter which field the pages are ordered by. Used to allow sorting by a custom field or a strictly specified one.
Accepts 4 arguments:
  1. The current order_by field.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_order_by','custom_order_by', 10, 4);
function custom_order_by( $order_by, $widget_args, $widget_values, $menu_class ){
       $order_by = 'post_date'; //order all widgets by date
       return $order_by;
}
advanced_sidebar_menu_child_pages
Filter which pages are used to create the child pages menu of the current page. Used to include or exclude custom pages from the child menu(s).
Accepts 4 arguments:
  1. An array of the child pages.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_child_pages','change_child_pages', 10, 4);
function change_child_pages( $child_pages, $widget_args, $widget_values, $menu_class ){
       if( $menu_class->top_id == 2 ){ //if we are currently on page id 2
            $child_pages = array( 5, 7 ); //pages with ids 5 and 7 will display in child pages menu
       }
       return $child_pages;
}
advanced_sidebar_menu_page_widget_output
Filter the complete output of the page list widget. Used to customize the Advanced Sidebar Pages Menu widget output.
Accepts 4 arguments:
  1. The complete output.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_page_widget_output','change_widget_output', 10, 4);
function change_widget_output( $output, $widget_args, $widget_values, $menu_class ){
      $output = '<p>Widget Placeholder</p>'; //override the entire output
       return $output;
}
advanced_sidebar_menu_list_pages_args
Use to change the arguments used when calling get_pages() or wp_list_page() during render of the menu. Runs after the arguments have been parsed.
Accepts 2 arguments:
  1. The arguments for the menu.
  2. The complete object used to list pages with properties set.
add_filter('advanced_sidebar_menu_list_pages_args','change_list_page_args', 10, 2);
function change_list_page_args( $args, $class ){
       $args[ 'sort_order' ] = 'DESC';
       return $args;
}

 

Category Widget

advanced_sidebar_menu_after_widget_form
Runs at the end of the widget form within the admin. Used to add custom form fields to the widgets.
Accepts 2 arguments:
  1. The widget values.
  2. The complete widget object.
add_action('advanced_sidebar_menu_after_widget_form','custom_form_field', 10, 2);
function custom_form_field( $values, $class ){
       echo '<input type="text" name="custom" value="' . $values[ 'include_parent' ] . '" />';
}
advanced_sidebar_menu_category_widget_update
Runs during a widget save. Used to change values being saved in the widgets.
Accepts 2 arguments:
  1. The widget values.
  2. The old widget values.
add_action('advanced_sidebar_menu_category_widget_update','change_widget_values', 10, 2);
function change_widget_values( $new_values, $old_values ){
       $new_values[ 'exclude' ] = $old_values[ 'exclude' ];
       return $new_values;
}
advanced_sidebar_menu_taxonomy
Filters the taxonomy used when determining where to display the widget and which terms to display. Used to display the menu on a custom taxonomy (defaults to category).
Accepts 4 arguments:
  1. The current taxonomy.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_taxonomy','custom_taxonomy', 10, 4);
function custom_taxonomy( $taxonomy, $widget_args, $widget_values, $menu_class ){
       $taxonomy = 'product_category'; //changes the taxonomy to product_category
       return $taxonomy;
}
advanced_sidebar_menu_proper_single
Filter where the menu may be used. Used to allow rendering the menu on pages like home that are not a proper single page.
Accepts 4 arguments:
  1. If this is a proper single page where the menu should display.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_proper_single','display_on_homepage', 10, 4);
function display_on_homepage( $is_displayed, $widget_args, $widget_values, $menu_class ){
       if( is_home() ) $is_displayed = true;
       return $is_displayed;
}
advanced_sidebar_menu_category_orderby
Filter what field the categories are ordered by. Used to order categories by a specified field.
Accepts 4 arguments:
  1. Field the categories are ordered by (defaults to name).
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_category_orderby','order_by_term_id', 10, 4);
function order_by_term_id( $orderby, $widget_args, $widget_values, $menu_class ){
       $orderby = 'term_id'; //orders categories by term id
       return $orderby;
}
advanced_sidebar_menu_category_ids
Filter what categories will be added to the menu. Used to specify a different list of category ids.
Accepts 4 arguments:
  1. Array of category ids which will be displayed.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_category_ids','change_displayed_categories', 10, 4);
function change_displayed_categories( $cat_ids, $widget_args, $widget_values, $menu_class ){
       $cat_ids = array( 4, 5, 8 ); //categories with ids 4, 5, and 8, will always display
       return $cat_ids;
}
advanced_sidebar_menu_category_widget_output
Filter the complete output of the category list widget. Used to customize the Advanced Sidebar Categories Menu widget output.
Accepts 4 arguments:
  1. The complete output.
  2. The widget arguments.
  3. The widget values.
  4. The full menu object.
add_action('advanced_sidebar_menu_category_widget_output','change_widget_output', 10, 4);
function change_widget_output( $output, $widget_args, $widget_values, $menu_class ){
      $output = '<p>Widget Placeholder</p>'; //override the entire output
      return $output;
}