cherry-framework-docs/08. cherry-utility.md at master · CherryFramework/cherry-framework-docs

Cherry Utility

General Description

The module is used for implementing:

Posts attributes, tags and categories
- Title
- Content
- Excerpt
- More button
- Tags and categories description
Posts, categories and tags metadata
- Post categories
- Post tags
- Post publish date
- Post author
- Post comments number
- Number of posts in category
- Number of posts in a tag
Media elements
- Image preview
- Video
Additional utilities
- Post link
- Link on tag or category
- Text cut
- Thumbnail size
- Get tags or categories array

Module arguments

The module can take arguments array with the following keys:

utility - array - sub modules array
- media - sub-module that works with medial elements like images and videos
- attributes - sub-module that works with posts, tags and categories attributes like: title, content, description, read more button
- meta-data - sub-module that works with posts, categories and tags metadata like: post author, publish date, number of comments, etc.
meta_key - array - meta keys array
- term_thumb - option where tags and categories thumbnails key should be added. cherry_thumb by default. The given key can be used in cherry-term-meta module. It should be added in arguments in fields option.

Example:

'cherry-utility' => array(
	'autoload'  => true,
	'args'      => array(
		'utility' => array(
			'media',
			'attributes',
			'meta-data',
		),
		'meta_key'  => array(
			'term_thumb' => 'cherry_thumb',
		),
	),
);

Sub-modules

If autoload argument value of the module is true, it is enough to get it from the $core->modules['cherry-utility'] to start working with modules.

Example:

$utility = $core->modules['cherry-utility']->utility;

where $core - Cherry_Core instance.

In case autoload argument value is false, the module should be initialized via init_module() core method. After that you can receive the module from $core->modules['cherry-utility'] core.

In the theme you can receive the module toolkit through theme_name_utility() function.

Example:

$utility = your_prefix_utility();

Сherry_Attributes_Utilit

path - cherry-framework\modules\cherry-utility\inc\cherry-attributes-utilit.php

The following methods are stored in the class:

get_title

The method returns post title, tag or category. The method has the following parameters:

$args - array - array with arguments for title customization. The array can contain the following keys with values
- visible - boolean - show/hide title. The key can take two values true/false. If false returns empty string. By default: true
- length - int - show/hide title. Returned title length. 0 value returns the entire title. By default: 0
- trimmed_type - string - title cut method, works with length attribute. Has two values: word - word cut, char - characters cut. By default: word
- ending - string - character that is displayed after title cut. By default: …
- html - string - returned HTML-format (the string contains special characters %1$s). By default: <h3 %1$s><a href="%2$s" %3$s rel="bookmark">%4$s</a></h3>
  - %1$s - Contains class key value, mentioned below. Displayed in - class="class_name" format
  - %2$s - Contains post URL
  - %3$s - Contains uncut post title, even if length is nonzero. Displayed in - title ="post/ category/ tag title" format
  - %4$s - Contains post title
- class - string - title CSS-class. By default: ""
- title - string - HTML-tag title. By default: ""
- echo - boolean - title display method true/false. If true displays the result immediately. By default: false
$type - string - entity type from which you need to get a title. Has two values post - post and term - categories, tag. By default: post
$ID - int - ID of any entity, listed in $type attribute. No need to indicate if the function is used inside posts loop. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Post title display
$utility->attributes->get_title( array(
	'visible'       => true,
	'length'        => 0,
	'trimmed_type'  => 'word',
	'ending'        => '&hellip;',
	'html'          => '<h1 %1$s><a href="%2$s" title="%3$s" rel="bookmark">%4$s</a></h1>',
	'class'         => 'post-title',
	'echo'          => true,
) );

// Category title display
$utility->attributes->get_title(
	array(
		'visible'       => true,
		'length'        => 5,
		'trimmed_type'  => 'word',
		'ending'        => '&hellip;',
		'html'          => '<h2 %1$s><a href="%2$s" title="%3$s" rel="bookmark">%4$s</a></h2>',
		'class'         => 'term-title',
		'echo'          => true,
	),
	'term',
	256
);

get_content

The method returns post content or excerpt and tag or category description.

The method has the following parameters get_content( $args = array(), $type = 'post', $ID = 0):

$args - array - content settings arguments array. The array can contain the following keys with values
- visible - boolean - show/hide content. The key can take two values true/false. If false returns empty string. By default: true
- content_type - string - displayed content type. By default: post_content. Key has three values:
  - post_content - displays post content
  - post_excerpt - displays post description. If this value is set without description, it displays the content or its part depending on length parameter value
  - term_description - this value is set automatically if $type is term
- length - int - returned content length. 0 value returns the entire content. By default: 0
- trimmed_type - string - content cut method, works with length attribute. Has two values:
  - word - word cut
  - char - characters cut
- ending - string - character that is displayed after content cut. By default: …
- html - string - returned HTML-format (the string contains special characters %1$s). By default: <p %1$s>%2$s</p>
  - %1$s - contains class key value, mentioned below. Displayed in - class="class_name" format
  - %2$s - includes content depending on content_type argument value
- class - string - content CSS-class. By default: ""
- echo - boolean - content display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$type - string - entity type from which you need to get a content. Has two values post - post and term - categories, tag. By default: post
$ID - int - ID any entity, listed in $type attribute. No need to indicate if the function is used inside posts loop. If $type is term, $ID attribute is a must. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Post content display.
$utility->attributes->get_content( array(
	'visible'      => true,
	'content_type' => 'post_content',
	'length'       => 0,
	'trimmed_type' => 'word',
	'ending'       => '&hellip;',
	'html'         => '<p %1$s>%2$s</p>',
	'class'        => 'post-content',
	'echo'         => true,
) );

// Category description display.
$utility->attributes->get_content(
	array(
		'visible'      => true,
		'length'       => 55,
		'trimmed_type' => 'word',
		'ending'       => '&hellip;',
		'html'         => '<p %1$s>%2$s</p>',
		'class'        => 'term-description',
		'echo'         => true,
	),
	$type = 'term',
	$ID = 348
);

get_button

The method returns post button, tag or category.

The method has the following parameters get_button($args = array(), $type = 'post', $ID = 0):

$args - array - button customization arguments array. The array can contain the following keys with values:
- visible - boolean - show/hide button. The key can take two values true/false. If false returns empty string. By default: true
- text - string- button text. If the argument is empty, the button is not displayed and the function returns empty string. By default: ""
- icon - string - button icon. By default: ""
- html - string - returned HTML-format (the string contains special characters %1$s). By default: <a href="%1$s" %2$s %3$s><span class="btn__text">%4$s</span>%5$s</a>:
  - %1$s - contains post, category or tag link, depending on the $type attribute value
  - %2$s - contains post/category/tag title. Displayed in - title="post/ category/ tag" format
  - %3$s - contains class key value, mentioned below. Displayed in - class="class_name" format
  - %4$s - contains text attribute value
  - %5$s - contains image attribute value
- class - string - button CSS-class
- class - string - button CSS-class. By default: btn
- title - string - HTML-tag title <a>. By default: **"" **
- echo - boolean - button display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$type - string - entity type from which you need to get a button. Has two values post - post and term - categories, tag. By default: post
$ID - int - ID of any entity, listed in $type attribute. No need to indicate if the function is used inside posts loop. If $type is term, $ID attribute is a must. By default: 0clear

Example:

// Display post button.
$utility->attributes->get_button( array(
	'visible' => true,
	'text'    => esc_html__( 'Read More', 'text-domain' ),
	'icon'    => '<i class="material-icons">arrow_forward</i>',
	'class'   => 'btn',
	'html'    => '<a href="%1$s" title="%2$s" %3$s><span class="btn__text">%4$s</span>%5$s</a>',
	'echo'    => true,
) );

// Display category button.
$utility->attributes->get_button(
	array(
		'visible' => true,
		'text'    => esc_html__( 'Read More', 'text-domain' ),
		'icon'    => '<i class="material-icons">arrow_forward</i>',
		'class'   => 'btn',
		'html'    => '<a href="%1$s" title="%2$s" %3$s><span class="btn__text">%4$s</span>%5$s</a>',
		'echo'    => true,
	),
	$type = 'term',
	$ID = 129
);

Cherry_Meta_Data_Utilit

path - cherry-framework\modules\cherry-utility\inc\cherry-meta-data-utilit.php

The following methods are contained in this class:

get_terms

The method returns post tags or categories depending on the listed parameters.

The method has the following parameters get_terms( $args = array() , $ID = 0 ):

$args - array - arguments array. The array can contain the following keys with values:
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- type - string - received data type. The key has 2 values (dy default: category):
  - category - displays category
  - post_tag - displays tags
- icon - string - icon. By default: ""
- prefix - string - icon/ category list/ tags prefix. By default: ""
- delimiter - string - category/tag delimiter. By default: " " (space)
- before - string - category/tags list HTML-wrapper start. By default: <div class="post-terms">
- after - string - category/tags list HTML-wrapper end. By default: </div>
- class - string - CSS-class. By default: post-term
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$ID - int - Post ID. No need to indicate if the function is used inside posts loop. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// post categories list display
$utility->meta_data->get_terms( array(
	'visible'   => 'true',
	'type'      => 'category',
	'icon'      => '<i class="material-icons">bookmark</i>',
	'delimiter' => ', ',
	'echo'      => false,
) );

// post tags list display
$utility->meta_data->get_terms( array(
	'visible'   => 'true',
	'type'      => 'post_tag',
	'icon'      => '<i class="material-icons">bookmark</i>',
	'delimiter' => ', ',
	'echo'      => true,
) );

get_author

The method returns post author.

The method has the following parameters get_author( $args = array() , $ID = 0 ):

$args - array - arguments. The array can contain the following keys with values:
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- icon - string - icon. By default: ""
- prefix - string - link prefix. By default: ""
- html - string - returned HTML-format (the string contains special characters %1$s). By default: %1$s<a href="%2$s" %3$s %4$s rel="author">%5$s%6$s</a>
  - %1$s - prefix key value
  - %2$s - author's posts page url
  - %3$s - <a> tag title. Displayed in - title="text" format. If title key not listed, the title is not displayed
  - %4$s - contains class key value. Displayed in - class="class_name" format
  - %5$s - includes icon listed in icon key
  - %6$s - contains author name
- title - string - <a> HTML-tag title. By default: ""
- class - string - CSS-class. By default: post-author
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$ID - int - Post ID. No need to indicate if the function is used inside posts loop. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Display post author
$utility->meta_data->get_author( array(
	'icon' => '<i class="material-icons">person</i>',
	'echo' => true,
) );

get_comment_count

The method returns post comments number depending on the listed parameters.

The method has the following parameters get_comment_count( $args = array() , $ID = 0 ):

$args - array - arguments. The array can contain the following keys with values
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- icon - string - icon. By default: ""
- prefix - string - link prefix. By default: ""
- sufix - string / function - displayed after comments number. Processes the special character %s. Example: _n_noop( '%s comment', '%s comments', 'text-domain' ). By default: %s
- html - string - returned HTML-format (the string contains special characters %1$s). By default: %1$s<a href="%2$s" %3$s %4$s>%5$s%6$s</a>
  - %1$s - prefix key value
  - %2$s - post comments url
  - %3$s - <a> tag title. Displayed in - title="text" format. If title key not listed, the title is not displayed
  - %4$s - contains class key value. Displayed in - class="class_name" format
  - %5$s - includes icon listed in icon key
  - %6$s - number of comments in the post
- title - string - <a> HTML-tag title. By default: ""
- class - string - CSS-class. By default: post-comments-count
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$ID - int - Post ID. No need to indicate if the function is used inside posts loop. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Post comments number display
$utility->meta_data->get_comment_count( array(
	'visible' => 'true',
	'icon'    => '<i class="material-icons">chat_bubble_outline</i>',
	'sufix'   => array( 'single' => '%s comment', 'plural' => '%s comments' ),
	'echo'    => true,
) );

get_date

The method returns post date depending on the listed arguments.

The method has the following attributes get_date( $args = array() , $ID = 0 ):

$args - array - arguments. The array can contain the following keys with values
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- icon - string - icon. By default: ""
- prefix - string - link prefix. By default: ""
- html - string - returned HTML-format (the string contains special characters %1$s). By default: %1$s<a href="%2$s" %3$s %4$s><time datetime="%5$s">%6$s%7$s</time></a>:
  - %1$s - prefix key value
  - %2$s - blog page url
  - %3$s - <a> tag title. Displayed in - title="text" format. If title key not listed, the title is not displayed
  - %4$s - contains class key value. Displayed in - class="class_name" format
  - %5$s - publish date format in Y-m-d\TH:i:sP date format
  - %6$s - includes icon listed in icon key
  - %7$s - post publish date format. The format is listed in the admin panel Settings -> General -> Date Format
- title - string - <a> HTML-tag title. By default: ""
- class - string - CSS-class. By default: post-date
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$ID - int - Post ID. No need to indicate if the function is used inside posts loop. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Publish date display.
$utility->meta_data->get_date( array(
	'icon' => '<i class="material-icons">schedule</i>',
	'echo' => true,
) );

get_post_count_in_term

The method returns category/tag posts number, depending on the listed arguments.

The method has the following attributes get_post_count_in_term( $args = array() , $ID = 0 ).

$args - array - arguments. The array can contain the following keys with values
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- icon - string - icon. By default: ""
- prefix - string - category/tag posts prefix. By default: ""
- sufix - string / function - displayed after posts number in category/tag. Processes the special character Example: _n_noop( '%s post', '%s posts', 'text-domain' ). By default: %s
- html - string - returned HTML-format (the string contains special characters %1$s). By default: %1$s<a href="%2$s" %3$s %4$s rel="bookmark">%5$s%6$s</a>:
  - %1$s - prefix key value
  - %2$s - categories/ tags page url
  - %3$s - <a> tag title. Displayed in - title="text" format. If title key not listed, the title is not displayed in <a> tag
  - %4$s - includes class argument value. Displayed in class="class_name" format
  - %5$s - includes icon listed in icon key
  - %6$s - contains categories/tags posts count and suffix attribute value
- title - string - <a> HTML-tag title. By default: ""
- class - string - CSS-class. By default: post-count
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$ID - int - category/tag ID. Compulsory attribute. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// posts in category/ tag display.
$utility->meta_data->get_post_count_in_term( array(
	'icon'  => '<i class="material-icons">schedule</i>',
	'sufix' => array(
		'singular' => '%s post',
		'plural'   => '%s posts',
		'domain'   => 'text-domain',
		'context'  => false,
	),
	'echo' => true,
) );

Cherry_Media_Utilit

path - cherry-framework\modules\cherry-utility\inc\cherry-media-utilit.php

The following methods are contained in this class:

get_image

The method returns category/tag/ post HTML thumbnails.

The method has the following attributes get_image( $args = array(), $type = 'post', $ID = 0 ):

$args - array - arguments. The array can contain the following keys with values
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- size - string - image size. By default: apply_filters( 'cherry_normal_image_size', 'post-thumbnail' )
- mobile_size - string - image size on mobile device. By default: apply_filters( 'cherry_mobile_image_size', 'post-thumbnail' )
- html - string - returned HTML-format (the string contains special characters %1$s). By default: <a href="%1$s" %2$s><img src="%3$s" alt="%4$s" %5$s></a>:
  - %1$s - post/category/tag page url
  - %2$s - includes class argument value. Displayed in class="class_name" format
  - %3$s - image src
  - %4$s - post/ category/ tag title
  - %5$s - width, height attributes for <img> tag, displayed in format width="" height="". Will not be displayed if is false
- class - string - CSS-class. By default: wp-image
- placeholder - boolean - show/hide placeholder if thumbnail is absent. By default: true
- placeholder_background - string - placeholder background color. Color value should be set without #. By default: 000
- placeholder_foreground - string - placeholder text color. Color value should be set without #. By default: fff
- placeholder_title - string - placeholder title text color. If value is undefined, image size is displayed. By default: ""
- html_tag_suze - boolean - show/hide <img> tag. Included in special character %5$s in html key. By default: true
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$type - string - entity type from which you need to get a button. Has two values post - post and term - categories, tag. By default: post
$ID - int - $type attribute entity ID. No need to indicate if the function is used inside posts loop. If $type attribute is term, $ID attribute is compulsory. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Display number of posts in category/tag.
$utility->media->get_image( array(
	'html'          => '&lt;span style="background-image: url(\'%3$s\');"%4$s %2$s&gt;&lt;/span&gt;',
	'class'         => 'term-img',
	'size'          => 'medium',
	'mobile_size'   => 'thumbnail',
) );

get_video

The method return post video HTML (it also supports other oembed objects).

The method has the following attributes get_video( $args = array(), $ID = 0 ):

$args - array - arguments. The array can contain the following keys with values
- visible - boolean - show/hide. The key can take two values true/false. If false returns empty string. By default: true
- size - string - oembed object size. By default: apply_filters( 'cherry_normal_video_size', 'post-thumbnail' )
- mobile_size - string - oembed object size on mobile screen. By default: apply_filters( 'cherry_mobile_video_size', 'post-thumbnail' )
- class - string - CSS-class. By default: wp-video
- echo - boolean - display method true/false. If true displays the result immediately. false value allows to save the result in a variable. By default: false
$ID - int - $type attribute entity ID. No need to indicate if the function is used inside posts loop. By default: 0

Example:

$utility = $core->modules['cherry-utility']->utility;

// Posts number display in category/tag.
$utility->media->get_video( array(
	'size'        => 'medium',
	'mobile_size' => 'thumbnail',
) );

Cherry_Satellite_Utilit

path - cherry-framework\modules\cherry-utility\inc\cherry-satellite-utilit.php

Class contains the following methods:

get_post_object

The method returns post object.

The method has the following attributes get_post_object( $ID = 0 ):

$ID - int - post ID

get_term_object

The method returns category/tag object depending on the listed $ID.

The method has the following attributes get_term_object( $ID = 0 ):

$ID - int - category/tag ID

get_post_permalink

The method returns post URL.

get_term_permalink

Method url to category/tag depending on the listed $ID.

The method has the following attributes get_term_permalink( $ID = 0 ):

$ID - int - category/tag ID

cut_text

Text cut method.

The method has the following attributes cut_text( $text, $length, $trimmed_type = 'word' , $after ):

text - string - text to cut. By default: ""
length - int - words/characters length. By default: null
trimmed_type - string (by default: word):
- word - word cut
- char - characters cut
after - string - character that is displayed after content cut. By default: ""

get_thumbnail_size_array

The method returns an array with image height and width in px.

The method has the following attributes get_thumbnail_size_array( $size ):

size - string - thumbnail registered size slug. By default: ""

get_terms_array

The method returns categories/tags array. Array (id => name) format or in dependency of listed array attributes (slug => name).

The method has the following attributes get_terms_array( $tax = 'category', $key = 'slug' ):

tax - string - taxonomy type (by default: category). Has three values:
- category
- post_tag
- post_format
key - string - key in array format (by default: slug). Has two values:
- slug
- term_id

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cherry Utility

General Description

Module arguments

Sub-modules

Сherry_Attributes_Utilit

get_title

get_content

get_button

Cherry_Meta_Data_Utilit

get_terms

get_author

get_comment_count

get_date

get_post_count_in_term

Cherry_Media_Utilit

get_image

get_video

Cherry_Satellite_Utilit

get_post_object

get_term_object

get_post_permalink

get_term_permalink

cut_text

get_thumbnail_size_array

get_terms_array

FilesExpand file tree

08. cherry-utility.md

Latest commit

History

08. cherry-utility.md

File metadata and controls

Cherry Utility

General Description

Module arguments

Sub-modules

Сherry_Attributes_Utilit

get_title

get_content

get_button

Cherry_Meta_Data_Utilit

get_terms

get_author

get_comment_count

get_date

get_post_count_in_term

Cherry_Media_Utilit

get_image

get_video

Cherry_Satellite_Utilit

get_post_object

get_term_object

get_post_permalink

get_term_permalink

cut_text

get_thumbnail_size_array

get_terms_array