Skip to content

Commit

Permalink
Merge pull request #1043 from INN/1028-lmp-filters-docs
Browse files Browse the repository at this point in the history 
Add docs for Load More Posts filters
  • Loading branch information
@aschweigert
aschweigert committed Jan 6, 2016
2 parents 2065542 + 6e80f06 commit 4d25328
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 82 deletions.
189 changes: 108 additions & 81 deletions docs/developers/hooksfilters.rst
View file
Expand Up @@ -6,116 +6,143 @@ Homepage template filters

**filter: largo_homepage_feature_stories_list_maximum**

Filter the number of posts to display in the list of feature stories in 'HomepageSingleWithFeatured' templates.
Filter the number of posts to display in the list of feature stories in 'HomepageSingleWithFeatured' templates.

*args: $max*

------------
*args: $max*

filter: **largo_homepage_series_stories_list_minimum**

*args: $min*

Filter the minimum number of posts to show in a series list in the
HomepageSingleWithSeriesStories homepage list.
*args: $min*

This is used in the query for the series list of posts in the same series
as the main feature. If fewer than this number of posts exist, the list
is hidden and the headline dominates the full box.
Filter the minimum number of posts to show in a series list in the HomepageSingleWithSeriesStories homepage list.

------------
This is used in the query for the series list of posts in the same series as the main feature. If fewer than this number of posts exist, the list is hidden and the headline dominates the full box.

filter: **largo_homepage_series_stories_list_maximum**

*args: $max*

Filter the maximum number of posts to show in a series list in the
HomepageSingleWithSeriesStories homepage list.
*args: $max*

This is used in the query for the series list of posts in the same series
as the main feature. This is the maximum number of posts that will display
in the list.
Filter the maximum number of posts to show in a series list in the HomepageSingleWithSeriesStories homepage list.

------------
This is used in the query for the series list of posts in the same series as the main feature. This is the maximum number of posts that will display in the list.

filter: **largo_homepage_topstories_post_count**

*args: $showposts*
*args: $showposts*

Filter the number of posts that are displayed in the right-hand side of the
Top Stories homepage template.
Filter the number of posts that are displayed in the right-hand side of the Top Stories homepage template.

This is used in the query for the list of posts in the "Homepage Featured"
taxonomy. If more than 3 posts are found, they will display under a
"More Headlines" heading, just as headline links.
This is used in the query for the list of posts in the "Homepage Featured" taxonomy. If more than 3 posts are found, they will display under a "More Headlines" heading, just as headline links.

Other filters and actions
-------------------------

**filter: largo_registration_extra_fields**
filter: **largo_registration_extra_fields**

Called directly before the `[largo_registration_form]` shortcode has finished executing. You can append to this any addition form fields that you want to process.

**Usage:**

Passed in is an array of values of post variables generated if a user is trying the form for a second time. You can use these to pre fill your extra field inputs.

Also passed in is a WP_Error object that stores all the generated errors for the page. Use this if you'd like to display an error message on the erroneous field. ::

function filter_function_name($values, $errors) {
# ...
}
add_filter('largo_registration_extra_fields', 'filter_function_name');

action: **largo_validate_user_signup_extra_fields**

Called directly before form values from the `[largo_registration_form]`. Hook to this in order to validate any of the extra form data added with the largo_registration_extra_fields filter. For example, you could validate a captcha that was added to the form's fields.

**Usage:**

Called directly before the `[largo_registration_form]` shortcode has finished executing. You can append to this any addition form fields that you want to process.
Passed in is an array $result which contains all post data for the form. Contained in this array at $result["errors"] is a WP_Error object. Adding errors to this object will cancel form submission.

**Usage:**
Also passed in is an array that contains only the extra fields that were present. This is an easy way to check only the extra data. ::

Passed in is an array of values of post variables generated if a user is trying the form for a second time. You can use these to pre fill your extra field inputs.
function action_function_name($result,$extras) {
# ...
}
add_action('largo_validate_user_signup_extra_fields', 'action_function_name');

Also passed in is a WP_Error object that stores all the generated errors for the page. Use this if you'd like to display an error message on the erroneous field.
filter: **largo_lmp_args**

``function filter_function_name($values, $errors) {``
``# ... }``
``add_filter('largo_registration_extra_fields'``, ``'filter_function_name');``
*args: $args*

**action: largo_validate_user_signup_extra_fields**
Passed in this are the arguments for the Load More Posts WP_Query. An example usage would be to check if ``is_home()`` and then restrict the posts returned by the query to those in the homepage featured prominence term.

Called directly before form values from the `[largo_registration_form]`. Hook to this in order to validate any of the extra form data added with the largo_registration_extra_fields filter. For example, you could validate a captcha that was added to the form's fields.
filter: **largo_lmp_template_partial**

**Usage:**
*args: $partial, $post_query*

Passed in is an array $result which contains all post data for the form. Contained in this array at $result["errors"] is a WP_Error object. Adding errors to this object will cancel form submission.
Modifies the partial returned by ``largo_load_more_posts_choose_partial($post_query)`` to whatever you want.

Also passed in is an array that contains only the extra fields that were present. This is an easy way to check only the extra data.
If you are building a custom post type that uses a custom partial, you will need to use this filter to make the correct partial appear in the posts returned by the Load More Posts button on the homepage, on archive pages, and in the search results.

``function filter_function_name($result,$extras) {``
``# ... }``
``add_action('largo_validate_user_signup_extra_fields'``, ``'filter_function_name');``
When building your own filter, you must set the fourth parameter of add_filter to 2: ::

**filter: largo_lmp_args**
function your_filter_name($partial, $post_type, $context) {
// things
return $partials;
}
add_filter( 'largo_lmp_template_partial', 'your_filter_name', 10, 2);
^

Passed in this are the arguments for the Load More Posts WP_Query. An example usage would be to check if ``is_home()`` and then restrict the posts returned by the query to those in the homepage featured prominence term.
Without setting '2', your filter will not be passed the $post_type or $context arguments.
In order to set '2', you must set the third parameter of add_filter, which defaults to 10. It is safe to leave that at 10.

**filter: largo_post_social_links**
filter: **largo_partial_by_post_type**

*args: $output*
*args: $partial, $post_type, $context*

Called before ``largo_post_social_links()`` returns or echos the social icons. The argument ``$output`` is HTML, usually containing HTML looking like this: (Whitespace has been added for readability)
Modifies the partial returned by ``largo_get_partial_by_post_type`` to whatever you want.

.. code::
If you are building a custom post type that uses a custom partial, you will need to use this filter to make the correct partial appear in the posts returned by the Load More Posts button on the homepage, on archive pages, and in the search results.

<div class="largo-follow post-social clearfix">
<span class="facebook">
<a target="_blank" href="http://www.facebook.com/sharer/sharer.php?u= ...">
<i class="icon-facebook"></i>
<span class="hidden-phone">Like</span>
</a>
</span>
<span class="twitter">
<a target="_blank" href="https://twitter.com/intent/tweet?text= ...">
<i class="icon-twitter"></i>
<span class="hidden-phone">Tweet</span>
</a>
</span>
<span class="print">
<a href="#" onclick="window.print()" title="Print this article" rel="nofollow">
<i class="icon-print"></i>
<span class="hidden-phone">Print</span>
</a>
</span>
<span data-service="email" class="email custom-share-button share-button">
<i class="icon-mail"></i>
<span class="hidden-phone">Email</span>
</span>
</div>
When building your own filter, you must set the fourth parameter of add_filter to 3: ::

function your_filter_name($partial, $post_type, $context) {
// things
return $partial;
}
add_filter('largo_partial_by_post_type', 'your_filter_name', 10, 3);
^

Without setting '3', your filter will not be passed the $post_type or $context arguments.
In order to set '3', you must set the third parameter of add_filter, which defaults to 10. It is safe to leave that at 10.

filter: **largo_post_social_links**

*args: $output*

Called before ``largo_post_social_links()`` returns or echos the social icons. The argument ``$output`` is HTML, usually containing HTML looking like this: (Whitespace has been added for readability) ::

<div class="largo-follow post-social clearfix">
<span class="facebook">
<a target="_blank" href="http://www.facebook.com/sharer/sharer.php?u= ...">
<i class="icon-facebook"></i>
<span class="hidden-phone">Like</span>
</a>
</span>
<span class="twitter">
<a target="_blank" href="https://twitter.com/intent/tweet?text= ...">
<i class="icon-twitter"></i>
<span class="hidden-phone">Tweet</span>
</a>
</span>
<span class="print">
<a href="#" onclick="window.print()" title="Print this article" rel="nofollow">
<i class="icon-print"></i>
<span class="hidden-phone">Print</span>
</a>
</span>
<span data-service="email" class="email custom-share-button share-button">
<i class="icon-mail"></i>
<span class="hidden-phone">Email</span>
</span>
</div>

Template Hooks
--------------
Expand All @@ -124,15 +151,15 @@ Template Hooks

Sometimes you may want to fire certain functions or include additional blocks of markup on a page without having to modify or override an entire template file.

WordPress allows you to define custom action hooks using the `do_action() <http://codex.wordpress.org/Function_Reference/do_action>`_ function like so:
WordPress allows you to define custom action hooks using the `do_action() <http://codex.wordpress.org/Function_Reference/do_action>`_ function like so: ::

``do_action( 'largo_top' );``
do_action( 'largo_top' );

and then from functions.php in a child theme you can use the `add_action() <http://codex.wordpress.org/Function_Reference/add_action>`_ function to fire another function you define to insert markup or perform some other action when the do_action() function is executed, for example:
and then from functions.php in a child theme you can use the `add_action() <http://codex.wordpress.org/Function_Reference/add_action>`_ function to fire another function you define to insert markup or perform some other action when the do_action() function is executed, for example: ::

``add_action( 'largo_top', 'largo_render_network_header' );``
add_action( 'largo_top', 'largo_render_network_header' );

which would call the largo_render_network_header function when the largo_top action is executed.
This usage would call the ``largo_render_network_header`` function when the largo_top action is executed.

We are in the process of adding a number of action hooks to Largo to make it easier for developers to modify templates without having to completely replace them in a child theme.

Expand All @@ -149,22 +176,22 @@ Here is the current list of hooks available in Largo (available as of v.0.4):
- **largo_after_header** - after the main <header> element
- **largo_after_nav** - after the nav, before #main opening div tag
- **largo_main_top** - directly after the opening #main div tag

**home.php**

These actions are run on all homepage templates, including the Legacy Three Column layout.

- **largo_before_sticky_posts** - Runs in the main column, before the sticky post would be rendered
- **largo_after_sticky_posts** - Runs in the main column, after where the sticky post would be rendered, before the homepage bottom area.
- **largo_after_homepage_hottom** - Runs after the homepage bottom area, before the termination of the main column.

**sidebar.php**

- **largo_before_sidebar** - before the sidebar opening div tag
- **largo_before_sidebar_widgets** - after the opening div tag but before the first widget
- **largo_after_sidebar_widgets** - after the last widget but before the closing div tag
- **largo_after_sidebar** - after the closing div tag

**footer.php**

- **largo_before_footer** - after the closing div tag for #page but before the .footer-bg (this also comes after the optional "before footer" widget area that can be activated from the layout tab of the theme options
Expand All @@ -174,7 +201,7 @@ These actions are run on all homepage templates, including the Legacy Three Colu
- **largo_before_footer_close** - after the boilerplate but still inside the footer container
- **largo_after_footer** - after the closing <div> tag for .footer-bg but before the sticky footer
- **(wp_footer)** - if you need to insert anything just before the closing <body> tag use the wp_footer hook

**single.php**

- **largo_before_post_header** - inside <article> but before the post <header> element
Expand Down
4 changes: 3 additions & 1 deletion docs/developers/index.rst
View file
Expand Up @@ -57,19 +57,21 @@ A few brief technical notes that might be helpful as you get started:

technicalnotes
grunt-commands
hooksfilters

Function Reference
------------------

NOTE: the function reference is a work-in-progress and may not be very useful at the moment.

You can always `read Largo's source on Github <https://github.com/INN/Largo>`_.
It may be helpful to `read Largo's source on Github <https://github.com/INN/Largo>`_. If you discover insight there that is not included in these docs, please `let us know <#contributing-to-largo>`_.

.. toctree::
:maxdepth: 2

/api/index
constants
hooksfilters

Bug Reports and Feature Requests
--------------------------------
Expand Down

0 comments on commit 4d25328

Please sign in to comment.