Filters and actions
In this document we will go through the different filters you can use to modify the content of an article while it's being rendered. All filters has an array with the following variables:
- article - The article object
- post - Wordpress post object (may be false if no post is connected to the article)
- list - Instance of the Arlima_List object that the article belongs to
- content - Empty string, this is where you put the content that should be accessible in the template
- count - Current article index in the list
- filter_suffix - The possibly used sufix for this filter (read more here)
The code looks in general something like this:
function my_xyz_callback($data) {
$data['content'] = '...'; // The content you want to put in the template
return $data;
}
add_filter('arlima_xyz', 'my_xyz_callback');With this filter you can insert content that's meant to be added to the beginning of the article. The content returned by the filter will be accessible in the article template through the variable "article_begin".
// Display the publish date in top of every article
function my_article_begin_hook( $data ) {
$date = date('D d, M Y', $data['article']['published']);
$data['content'] = sprintf('<div class="article-date">Published %s</div>', $date);
return $data;
}
add_filter('arlima_article_begin', 'my_article_begin_hook');With this filter you can insert content that's meant to be added to the end of the article. The content returned by this filter will be accessible in the article template through the variable "article_end".
// Display an ad after every third article
function my_article_end_hook( $data ) {
if( $data['count'] % 3 === 0 ) {
$data['content'] = my_cool_ad_function();
}
return $data;
}
add_filter('arlima_article_end', 'my_article_end_hook');Use this filter to modify the presentation of image attachments related to the article. The callback will get the following variables, in addition to the variables that's always provided (list, article, article counter and post).
- size_name The name of the image size (full, half, third, fourth, fifth or sixth)
- width The width that the image is supposed to have
- resized URL to the resized image
- source URL to the default attachment (will be false if no image is attached)
// Load large images via wordpress cdn
function my_article_image_hook( $data ) {
if( $data['source'] && $data['width'] > 300 ) {
$source = str_replace('http://', '', $data['source']);
$data['resized'] = sprintf('http://i0.wp.com/%s?w=%d', $source, $data['width']);
}
return $data;
}
add_filter('arlima_article_image', 'my_article_image_hook');When using this filter you can choose between overriding the value in $data['resized'] (which is used to
generate an IMG tag) or the value in $data['content']. Here's another example
// Only show images to logged in users (and load large images via wordpress cdn)
function my_article_image_hook( $data ) {
if( $data['source'] ) { // make sure we have an image
if( !is_user_logged_in() ) {
$data['content'] = '<div class="no-image">Images is only displayed to logged in users</div>';
}
elseif( $data['width'] > 300 ) {
$source = str_replace('http://', '', $data['source']);
$data['resized'] = sprintf('http://i0.wp.com/%s?w=%d', $source, $data['width']);
}
}
return $data;
}
add_filter('arlima_article_image', 'my_article_image_hook');If you don't want to display the image you should let the filter function return false instead of the $data array.
You can use the filter arlima_article_image_tag if you only want to decorate the HTML of the generated image.
// Add caption to arlima images displayed in full
function my_arlima_image_captions($html, $img_size, $article) {
if( $img_size == 'full' ) {
$attach = get_post($article['image']['attachment']);
$html = sprintf('<div class="img-wrapper">%s<div class="caption">%s</div></div>', $html, $attach->post_excerpt);
}
return $html;
}
add_filter('arlima_article_image_tag', 'my_arlima_image_captions', 10, 3);This filter can be used to modify the text content of the article. If you don't want any text content to be displayed you should return false instead of the $data array.
// Show comment count
function my_article_content_hook( $data ) {
$data['content'] = arlima_link_entrywords(trim($data['article']['content']), $data['article']['url']);
if( $data['post'] ) {
$num_comments = get_comment_count($data['post']->ID);
$data['content'] .= sprintf('<div class="comment-count">%s</div>', $num_comments['approved']);
}
return $data;
}
add_filter('arlima_article_content', 'my_article_content_hook');This filter can be used to send content of any type related to current article to the article template.
// Show related post
function my_article_relations_hook( $data ) {
if( $data['post'] ) {
$related_post_id = get_post_meta($data['post']->ID, 'my-related-post', true);
if( $related_post_id && ($related_post = get_post($related_post_id)) ) {
$related_post->url = get_permlink($related_post->ID);
$related_post->html_comment_stats = get_comment_count($related_post->ID);
$data['content'] = array(
'single' => true,
'posts' => array( $related_post )
);
}
}
return $data;
}
add_filter('arlima_article_related_content', 'my_article_relations_hook');This filter can be used to show a message to the user when a future posts comes up in the article list. Note that future posts is only included when previewing a list. If you don't want any message to be displayed you should return false.
# arlima_hidden_templates
Use this filter to hide certain templates from being available in the article editor. The filter callback should return an array with the name of the templates that should be hidden (file name without path and extension)
function hide_some_templates($hidden) {
$hidden[] = 'giant'; // Hide the template named giant.tmpl
return $hidden;
}
add_filter('arlima_hidden_templates', 'hide_some_templates');By default the labels of the templates in the article editor will be the file name of the template. You can however use this filter if you want to label the templates with something else. The filter callback should return an array with the keys being the names of the templates (file name without path and extension) and the values being the label used in the article editor.
function my_template_labels($labels) {
$labels['giant'] = 'A very large article';
$labels['super-cool-article'] = 'A very cool looking article';
return $labels;
}
add_filter('arlima_template_labels', 'my_template_labels');### \# arlima_image_quality
This filter is used to set the image quality of image versions generated by Arlima (default is 100)
function my_arlima_image_quality( $default_quality ) {
return is_mobile_website() ? 85 : 100;
}
add_filter('arlima_image_quality', 'my_arlima_image_quality');### \# arlima_template_object
This filter enables you to modify the object that is used to create the variables available in the article template. This filter is the last action taking place before the article is rendered.
### \# arlima_search_post_types
Makes it possible to modify which post types that is queried in the list manager when searching for posts
### \# arlima_tmpl_width
The article preview in the list manager will have the same width as the list that the article belongs to. You declare the width of the list when you relate the list to a page). You can, however, override the declared width by using the filter arlima_tmpl_width.
function my_arlima_tmpl_width( $preview_width, $list ) {
return 510;
}
add_filter('arlima_tmpl_width', 'my_arlima_tmpl_width', 10, 2);This filter can also be used to display two different versions of the same article.
function my_arlima_tmpl_width( $preview_width, $list ) {
$preview_width = array(658, 320); // Desktop and mobile width
return $preview_width;
}
add_filter('arlima_tmpl_width', 'my_arlima_tmpl_width', 10, 2);
- arlima_post_search
- arlima_save_list
- arlima_streamer_colors, arlima_streamer_images
- arlima_template_paths
- arlima_template_css
NOTICE! As of version 3.1 the article data is represented as an object instead of an array. Here you can read the class docs. The class implements ArrayAccess and Countable and can therefor still be used as an array (this may however become deprecated in the future)
The article array available in the filter callbacks and article templates (all variables may be undefined).
'id' => 0, // Article id
'image' => array(
'attachment' => 0, // Attachment ID of the image
'alignment' => '', // Alignment of the image
'size' => '' // The size of the image
),
'options' => array(
'preTitle' => '', // Text used as prefix in the article title
'streamerType' => 'extra', // Which type of streamer this article has
'streamerContent' => '', // The content of the possible streamer that this article has
'streamerColor' => '', // The background color of the possible streamer that this article has
'hideRelated' => false, // Whether or not to display related articles
'template' => '', // The templates used for this article (falls back on the default template of the list)
'format' => '', // The format label for this article
'scheduled' => '', // If this article is scheduled t be displayed at certain days and hours
'scheduledInterval' => '' // At which day and at which hours this scheduled article should be displayed
'sectionDivider' => '', // Whether or not this article is a "section divider"
'fileInclude' => '', // Path to PHP-file that should be included
'fileArgs' => '' // query string used as arguments when loading the included file
),
'post' => 0, // Post ID of possibly connected post
'title' => 'Unknown', // the title of the article
'content' => '', // the body content of the article
'size' => 24, // A level of importance (used as font size by Arlima)
'created' => 0, // timestamp for when the article was created
'published' => 0, // timestamp for when article is considered published (inherited from connected worpress post)
'parent' => -1 // At what index in the list the parent article can be found, will -1 if the article doesn't have a parent
'url' => '', // url of the article
'children' => array() // Array with child articles, if there is some