.. _template_functions:

#########
Functions
#########

.. _template_functions_wp:

**************************
Magic wp.*  function
**************************

The magic wp.* function allows you to use **all WordPress native functions**. Just replace the * with the function name you'd like to use, e.g. ``wp.get_post()``.

Post Status Notifier does not check if it makes sense and what the function returns. This is up to you. If the function does not exist, an empty string will be returned.

.. note::

    You can use all WordPress functions following this syntax:
    ``{{ wp.function_name(parameter) }}``

********
Examples
********

Here are some examples to demonstrate the flexibility of the wp.* function.

wp.get_userdata
~~~~~~~~~~~~~~~

This example uses the WordPress function ``get_userdata`` to retrieve the user data based on PSN's placeholder [post_author] which contains the user ID of the post author.

.. code-block:: jinja

    {{ wp.get_userdata( [post_author] ) }}

To work with the user data you can assign the result to a variable and then access the array keys using the dot separator.

.. code-block:: jinja

    {% set user_data = wp.get_userdata( [post_author] ) %}
    {{ user_data.first_name }}
    {{ user_data.last_name }}
    {{ user_data.user_login }}
    {{ user_data.user_url }}

For more inforamtion about ``get_userdata`` visit the `get_userdata codex page <http://codex.wordpress.org/Function_Reference/get_userdata>`_.


wp.get_post
~~~~~~~~~~~

This example uses the WordPress function ``get_post`` to retrieve the data of a post. The post ID comes from a custom field called "related_post".

.. code-block:: jinja

    {% set post_data = wp.get_post( [post_custom_field-related_post] ) %}
    <h1>{{ post_data.title }}</h1>

For more inforamtion about ``get_post`` visit the `get_post codex page <http://codex.wordpress.org/Function_Reference/get_post>`_.

wp.get_comments_number
~~~~~~~~~~~~~~~~~~~~~~

To include the number of comments for a post, you can use the function ``get_comments_number`` like this:

.. code-block:: jinja

    Comments: {{ wp.get_comments_number( [post_ID] ) }}

For more inforamtion about ``get_comments_number`` visit the `get_comments_number codex page <http://codex.wordpress.org/Template_Tags/get_comments_number>`_.

.. _template_functions_db:

**************************
Magic db.* function
**************************

The magic db.* function allows you to perform database queries to select data.

.. note::

    Only SQL starting with "SELECT" is allowed.

The following funtions are supported:

db.get_results
~~~~~~~~~~~~~~~~~~~~~~

This is a mapper for the WordPress method ``get_results`` of the global wpdb object: `codex.wordpress.org <http://codex.wordpress.org/wpdb#SELECT_Generic_Results>`_

It retrieves an array of objects representing the rows of the database table.

.. code-block:: jinja

    {% set sql = "SELECT * FROM wp_users WHERE ID < 10" %}
    {% set users = db.get_results(sql) %}
    {% for user in users %}
        {{user.user_email}},
    {% endfor %}

db.get_results_assoc
~~~~~~~~~~~~~~~~~~~~~~

This is a mapper for the WordPress method ``get_results`` of the global wpdb object: `codex.wordpress.org <http://codex.wordpress.org/wpdb#SELECT_Generic_Results>`_

It retrieves an associative array representing the rows of the database table.

.. code-block:: jinja

    {% set sql = "SELECT * FROM wp_users WHERE ID < 10" %}
    {% set users = db.get_results(sql) %}
    {% for user in users %}
        {{user.user_email}},
    {% endfor %}


db.get_row
~~~~~~~~~~~~~~~~~~~~~~

This is a mapper for the WordPress method ``get_row`` of the global wpdb object: `codex.wordpress.org <http://codex.wordpress.org/wpdb#SELECT_a_Row>`_

It retrieves one row of a table as an object.

.. code-block:: jinja
    
    {% set user = db.get_row("SELECT * FROM wp_users WHERE ID = 1;") %}
    {{ user.user_email }}

db.get_row_assoc
~~~~~~~~~~~~~~~~~~~~~~

This is a mapper for the WordPress method ``get_row`` of the global wpdb object: `codex.wordpress.org <http://codex.wordpress.org/wpdb#SELECT_a_Row>`_

It retrieves one row of a table as an associative array.

.. code-block:: jinja
    
    {% set user = db.get_row("SELECT * FROM wp_users WHERE ID = 1;") %}
    {{ user.user_email }}
    
db.get_var
~~~~~~~~~~~~~~~~~~~~~~

This is a mapper for the WordPress method ``get_var`` of the global wpdb object: `codex.wordpress.org <http://codex.wordpress.org/wpdb#SELECT_a_Variable>`_

It retrieves a single value of a database table.

.. code-block:: jinja
    
    {% set user_email = db.get_var("SELECT user_email FROM wp_users WHERE ID = 1;") %}
    {{ user_email }}

db.get_col
~~~~~~~~~~~~~~~~~~~~~~

This is a mapper for the WordPress method ``get_col`` of the global wpdb object: `codex.wordpress.org <http://codex.wordpress.org/wpdb#SELECT_a_Column>`_

It retrieves a one dimensional array.

.. code-block:: jinja
    
    {% set user_emails = db.get_var("SELECT user_email FROM wp_users WHERE ID < 10;") %}
    {% for email in user_emails %}
        {{email}},
    {% endfor %}