Skip to content
Michiel Tramper edited this page Mar 24, 2022 · 41 revisions

An atom is the lowest level component, such as a post title, sharing buttons or list of terms.

Each atom has unique properties, besides the common properties you may give to each atom or molecule. These are listed here. These properties also have default values.

Rendering an Atom

A set of properties is defined while rendering an atom in the following way:

MakeitWorkPress\WP_Components\Build::atom( string $atomname, array $properties );

The second parameter is the properties for the given atom. Properties are always in the form of an array.

The following gives an example for rendering an image, whose attachment ID is 71.

MakeitWorkPress\WP_Components\Build::atom( 'image', ['image' => 71] );

There is also a shorter function available:

wpc_atom( 'image', ['image' => 71] );

 

Archive Title

The archive title automatically displays an archive title if it is used within a post, category or taxonomy archive. Often, this is in the archive.php, category.php or taxonomy.php theme template file.

Property Type Description Default Values
custom string A custom title ''
types array The default titles for different kind of archives See below

Default values for types property

    [
        'author'    => __( 'Posts Author Archive: %s', 'components' ),
        'category'  => single_cat_title( '', false ),
        'day'       => sprintf( __( 'Daily Archives: %s', 'components' ), '<span>' . get_the_date() . '</span>' ),
        'default'   => isset(get_queried_object()->labels->name) ? get_queried_object()->labels->name : __( 'Blog Archives', 'components' ),
        'month'     => sprintf( __( 'Monthly Archives: %s', 'components' ), '<span>' . get_the_date('F Y') . '</span>' ),
        'search'    => sprintf( 
            _n( '%1$s result for: %2$s', '%1$s results for: %2$s', $wp_query->found_posts, 'components' ),
            '<span>' . number_format_i18n( $wp_query->found_posts ) . '</span>',
            '<span>' . get_search_query() . '</span>'
        ),  
        'tag'       => sprintf( __( 'Posts tagged: %s', 'mt' ) , '<span>' . single_tag_title( '', false ) . '</span>' ),
        'tax'       => single_term_title( '', false ),
        'year'      => sprintf( __( 'Yearly Archives: <span>%s</span>', 'mt' ), get_the_date('Y') )   
    ]

 

Author

The author element displays a post author box, with a possible image and description.

Property Type Description Default Values
attributes array Custom attributes See below
avatar string The avatar image element for get_avatar( $post->post_author, 100 )
description string Author Description get_the_author_meta( 'description' )
image_float string The float of the author avatar. Accepts 'none', 'left', 'center', 'right' 'none'
image_rounded boolean If the image should be rounded or not. true
job_title string An optional job title for the author ''
name string The name of the author get_the_author()
prepend string A custom string before the author's name ''
schema boolean Whether to display Microdata or not. Also removes schematic attribute. true
url string The url to the author's page esc_url( get_author_posts_url( $post->post_author ) )

Default values for attributes property

    [
        'itemprop'  => 'author',
        'itemscope' => 'itemscope',
        'itemtype'  => 'http://schema.org/Person'    
    ]

 

Breadcrumbs

The breadcrumbs element displays breadcrumbs for any type of content.

Property Type Description Default Values
attributes array Custom attributes See below
archive boolean If a link to the posts archive should be included in a post false
home string The text for the homepage crumb __('Home', 'components')
seperator string The seperator between breadcrumbs '&rsaquo;'
taxonomy boolean or string Adds the posts taxonomy in the breadcrumb. If set to true, takes the first taxonomy. If set to string, assumes that the given string is a taxonomy name. false
locations string The title values for the different breadcrumb locations See below

Default values for attributes property

    [
        'itemscope' => 'itemscope',
        'itemtype'  => 'http://schema.org/Breadcrumb'
    ]

Default values for locations property

The locations property indicates the titles that are used for the given location. For example, the breadcrumb at the 404 page is in this case: Home > 404

    [           
        '404'       => __('404', 'components'),
        'archive'   => isset(get_queried_object()->labels->name) ? get_queried_object()->labels->name : '',
        'author'    => '',
        'category'  => single_cat_title( '', false),
        'day'       => get_the_date(),
        'month'     => get_the_date('F Y'),
        'page'      => get_the_title(),
        'search'    => sprintf( __('Search Results: %s', 'components'), urldecode(get_query_var('s')) ), 
        'single'    => get_the_title(),
        'tag'       => single_tag_title( '', false ),
        'tax'       => single_term_title( '', false ), 
        'year'      => get_the_date('Y')
    ]

 

Button

Displays a button.

Property Type Description Default Values
attributes array Custom attributes See below
icon_after string The icon before the label. Accepts a FontAwesome string, such as 'fas fa-user' ''
icon_before string The icon after the label. Accepts a FontAwesome string, such as 'fas fa-user' ''
icon_visible string If the icon is visible by default or by hover. Accepts 'standard' or 'hover' 'standard'
label string The button label ''
size string The size of the button. Accepts 'none', 'small', 'large'. An empty size results in the default button. If set to none, renders a button without background, border and padding ''

Default values for the attributes property

If the key 'href' is set to 'post', it will link to the current post. Otherwise, it accepts a custom URL.

    'attributes'    => [
        'href'   => 'post',
        'target' => '_self'
    ],

 

Callback

Executes a function using call_user_func. Accepts the name of a function or a class method in the form of an array [$this, 'method']

Property Type Description Default Values
callback array or string The function that should be executed. ''

 

Cart

Displays a WooCommerce cart, for use in menus and pages. Requires the WooCommerce Plugin to function.

Property Type Description Default Values
cart boolean Whether to show the cart's contents or not. true
collapse boolean Whether to collapse the cart by default. A collapsed cart becomes visible by clicking the icon. true
icon boolean Whether to show a shopping icon or not true

 

Comments

Displays a section with a comments form and list of comments, using the comments_template function. May be used within posts.

Property Type Description Default Values
closed boolean If comments are closed. ! comments_open()
closed_text string The text when comments are closed __('Comments are closed.', 'components')
form string The comments form comment_form()
have_comments int If there are comments get_comments_number()
next string The text for the next comments page when using comments pagination '&rsaquo;'
paged boolean If comments are paged get_comment_pages_count() > 1 && get_option( 'page_comments' ) ? true : false
prev string The text for the previous comments page when using comments pagination '&lsaquo;'
seperate boolean If comments should be seperated by type false
template string The name of a custom template file ''
title string The title above the comments See below

Default values for title property

sprintf( 
        _n( 'One Response to %2$s', '%1$s Responses to %2$s', get_comments_number(), 'components' ),
        number_format_i18n( get_comments_number() ),
        get_the_title()
)

 

Content

Displays the content or excerpt from a post

Property Type Description Default Values
attributes array Custom content attributes ['itemprop' => 'text']
content string A string for displaying custom content ''
pages string Includes the pagination element for multi-page content wp_link_pages( ['echo' => false] )
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
type string The type of content, accepts 'content' or 'excerpt' 'content'

 

Copyright

Displays a copyright element, properly formatted with rich snippets.

Property Type Description Default Values
copyright string The copyright symbol '©'
date string The copyright date date('Y')
itemtype string The default itemtype for the copyrightHolder 'http://schema.org/Organization'
name string The name of the copyright holder ''

 

Date

Displays the date in a time element.

Property Type Description Default Values
attributes array Custom attributes for date ['datetime' => get_the_date('c'), 'itemprop' => 'datePublished']
date string The displayed date get_the_date()
icon string Optional FontAwesome icon before the date, such as 'fas fa-clock'. ''
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true

 

Description

Displays a description

Property Type Description Default Values
attributes array Custom attributes for description ['itemprop' => 'description']
description string The actual description ''
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
tag string The html tag used for displaying the description 'p'

 

Image

Displays an image wrapped in a figure element

Property Type Description Default Values
enlarge boolean Whether the image should be enlarged on hover or not. false
image string or int Accepts a complete tag, an integer to an attachment ID or a custom string. If set to a custom string, it will look for the image id in a meta key equal to that string ''
link boolean Accepts any url, linking the image. If set to post, gets the link of the current post. ''
post boolean Passes a post id. Can be used if the permalink does not work ''
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
size boolean The image size to load 'large'

 

List

Displays a simple unordered or ordered list

Property Type Description Default Values
grid boolean Display the list as a grid. false
grid_gap string The gap between grid items. 'default'
hover_item string The optional hover.css class applied to each item in the list. For this to work, hover should also be set to true while booting the instance. ''
items array The array of items. Each item should be an array with a title key, an optional icon (indicated by a FontAwesome icon class, such as 'fas fa-user'), optional description and optional link key. []
style string The style, either default or card (adds padding and a white background). 'default'
title_tag string The optional title tag for the list item title. 'h4'

Example

wpc_atom('list', [
    // 'animation' => 'bounce',
    'grid'      => true,
    // 'hoverItem' => 'grow',
    'items'     => [
        ['icon' => 'user', 'title' => __('Label'), 'link' => 'https://url.com', 'description' => __('A whole story'), 'column' => 'half'],
        ['icon' => 'user', 'title' => __('Label'), 'link' => 'https://url.com', 'description' => __('A whole story'), 'column' => 'half']
    ],
    'style'     => 'card'
]);

 

Logo

Displays a logo with accompanying rich snippets.

Property Type Description Default Values
attributes array The custom logo attributes. ['href' => esc_url( home_url('/') ), 'itemscope' => 'itemscope', 'itemtype' => 'http://schema.org/Organization',]
alt string The alt text for the logo '__('Logo', 'components')'
default array The default logo image. Also accepts integers for attachment ids. ['src' => '', 'height' => '', 'width' => '']
default_transparent array The logo for transparent headers. Also accepts integers for attachment ids. ['src' => '', 'height' => '', 'width' => '']
mobile array The logo image displayed for cellphones. Also accepts integers for attachment ids. ['src' => '', 'height' => '', 'width' => '']
mobile_transparent array The transparent logo image displayed for cellphones. Also accepts integers for attachment ids. ['src' => '', 'height' => '', 'width' => '']
mode string Accepts 'logo' to display the site logo, or 'title' to display the sites name 'logo'
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
size string The image size of the image that is loaded, such as 'medium' or 'full'. 'medium'
tablet array The logo image displayed for tablets. Also accepts integers for attachment ids. ['src' => '', 'height' => '', 'width' => '']
tablet_transparent array The transparent logo image displayed for tablets. Also accepts integers for attachment ids. 'large'
title string The title for the logo esc_attr( get_bloginfo('name') )
url string The (custom) url for the logo esc_url( get_bloginfo('url') )

 

Map

Displays a Google Map.

Property Type Description Default Values
center array The map center. ['lat' => 52.090736, 'lng' => 5.121420]
id string The map id. Change if you're using multiple maps at one page. 'wpcDefaultMap'
markers string The array of markers with either latitude and longitude or the address. For example, [['lat' => 52.090736, 'lng' => 5.121420]] or [['address' => 'Broadway, New York']] []
zoom int The map zoom level. 12

 

Menu

Displays a WordPress menu.

Property Type Description Default Values
attributes array The custom menu attributes. ['itemtype' => 'http://schema.org/SiteNavigationElement', 'itemscope' => 'itemscope']
args array Custom arguments for wp_nav_menu []
collapse boolean Whether submenu items should be collapsed for mobile menus or not true
dropdown boolean Whether to show submenu items or not true
hamburger array Accepts 'mobile' to display a hamburger menu under 767px viewport width, 'tablet' for under 1024px viewport width and 'always' to always display the hamburger menu. 'mobile'
indicator boolean If submenus should be indicated by a downward arrow true
menu string The logo image displayed for tablets ''
view string Custom menu style. Accepts dark for a dark mobile menu, fixed, left or right to display a hamburger menu variation. ''

 

Meta

Displays the values from a custom meta field

Property Type Description Default Values
after string A string echoed after the meta information ''
before string A string echoed before the meta information ''
key string The key for the custom meta field. ''
id int Passes a post id. get_the_ID()
meta string An optional string with meta information ''

 

Modal

Renders a modal, hidden by default. Can be made visible by own liking with a JavaScript click event.

Property Type Description Default Values
attributes array Custom modal attributes ['data' => ['id' => uniqid()]]
content string The content of the modal ''

 

Pagination

Displays a pagination element for use in archives, grids and single posts

Property Type Description Default Values
format string The format of the pagination link '/page/%#%'
next string The next text within the pagination '&rsaquo;'
pagination string An optional pagination element. Overwrites the default output of this atom. ''
prev string The previous text within the pagination '&lsaquo;'
size int The amount of pagination numbers 2
type string The type of pagination. Accepts 'numbers', 'arrows' (for archives or grids) or 'post' (for pagination at single posts). 'numbers'
query string The WP_Query object this pagination is related to. Required for arrows and numbers type. $wp_query

 

Rate

Displays a component with a certain rating value displayed by stars, which may optionally be influenced by visitors. The rating component stores it values in the components_rating meta field and the rating count in components_rating_count by default. These fields are also used for ajax-powered ratings.

Property Type Description Default Values
attributes array Custom rate attributes ['itemprop' => 'aggregateRating', 'itemscope' => 'itemscope', 'itemtype' => 'http://schema.org/AggregateRating']
author string An optional author for this review ''
author_type string The itemtype for this author 'http://schema.org/Person'
count string The count of ratings get_post_meta(get_the_ID(), 'components_rating_count', true)
id string The id for the post that is rated get_the_ID()
max string The maximum rating value 5
min string The minimum rating value 0
rate boolean If visitors can rate true
reviewed string The name of the item that is being reviewed ''
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
value string An optional author for this review get_post_meta(get_the_ID(), 'components_rating', true) ? get_post_meta(get_the_ID(), 'components_rating', true) : 0

 

Scroll

Renders a scroll button that moves away from its parent element, or scrolls to the top

Property Type Description Default Values
icon string By default, a mouse icon is displayed. Use this to display a custom font-awesome icon, for example, 'fas fa-angle-down' ''
top boolean If set to true, this element scrolls to top false

 

Search

Displays a search field, which optionally may have ajax powered search

Property Type Description Default Values
attributes array The custom attributes for the search atom See below
ajax boolean Enables the ajax search action false
all string The string for searching through all results __('View all search results', 'components')
collapse boolean If set to true, only shows a search icon that opens a form upon click false
form string The searchform get_search_form(false)
link string The link to the search page esc_url( get_search_link('') )
types array Limit the search to specific post types, expects post type names. ''

Default values for attributes property

The data attributes are used to define how the ajax search is performed.

    'data' => [
            'appear'    => 'bottom', // Determines from which direction posts apear, using scroll-reveal. Accepts bottom, top, left or right
            'delay'     => 300,      // Delay to start searching after typing
            'length'    => 3,        // The length of the search string to start querying with ajax
            'none'      => __('Bummer! No results found', 'components'), // The text when there are no results
            'number'    => 5         // The number of posts to query with ajax   
    ]

 

Share

Displays a set of sharing buttons

Property Type Description Default Values
color_background boolean If the sharing buttons should have a background true
enabled array The networks that are enabled [ 'facebook', 'twitter', 'linkedin', 'google-plus', 'pinterest', 'reddit', 'stumbleupon', 'pocket', 'whatsapp' ]
fixed boolean If the shared icons should be fixed to the left of the screen false
hover_item string The optional hover.css class applied to each social button. For this to work, hover should also be set to true while booting the instance. ''
share string The label at the beginning of the sharing icons __('Share:', 'wp-components')
networks array How the sharing buttons are build up See below

Default values for the networks property

The default sharing links are set-up with the networks attribute, and they get their sources from the following code:

    [
        'facebook'      => [ 'url' => 'http://www.facebook.com/sharer.php?u=' . $url, 'icon' => 'facebook' ], 
        'twitter'       => [ 'url' => 'http://twitter.com/share?url=' . $url . '&text=' . $title . '&via=' . $via, 'icon' => 'twitter' ], 
        'linkedin'      => [
            'url'   => 'http://www.linkedin.com/shareArticle?mini=true&url=' . $url . '&title=' . $title . '&source=' . $source, 
            'icon'  => 'linkedin'
        ], 
        'google-plus'   => [ 'url' => 'https://plus.google.com/share?url=' . $url, 'icon' => 'google-plus' ], 
        'pinterest'     => [
            'url'   => 'http://pinterest.com/pin/create/button/?url=' . $url . '&description=' . $title . '&media=' . $image, 
            'icon'  => 'pinterest'
        ], 
        'reddit'        => [ 'url' => 'http://www.reddit.com/submit?url=' . $url . '&title=' . $title, 'icon' => 'reddit-alien' ], 
        'stumbleupon'   => [ 'url' => 'http://stumbleupon.com/submit?url=' . $url . '&title=' . $title, 'icon' => 'stumbleupon' ],
        'pocket'        => [ 'url' => 'https://getpocket.com/edit.php?url=' . $url, 'icon' => 'get-pocket' ],
        'whatsapp'      => [ 'url' => 'whatsapp://send?text=' . $title . ' ' . $url, 'icon' => 'whatsapp' ]
   ]

Optionally, each network supports the 'title' key if it should display a text next to its icon.

The variables within these values are retrieved from the following code within the atom:

if( has_post_thumbnail($postID) ) {
    $id     = get_post_thumbnail_id( $postID );
    $image  = wp_get_attachment_image_url( $id, isset( $atom['size'] ) ? $atom['size'] : 'large' );
} else {
    $image  = '';
}

$image  = isset( $atom['image'] )   ? $atom['image']    : $image;
$source = isset( $atom['source'] )  ? $atom['source']   : get_bloginfo('name');
$title  = isset( $atom['title'] )   ? $atom['title']    : rawurlencode( get_the_title($postID) );
$url    = isset( $atom['url'] )     ? $atom['url']      : rawurlencode( get_permalink($postID) );
$via    = isset( $atom['via'] )     ? $atom['via']      : '';

 

Sidebar

Displays a sidebar

Property Type Description Default Values
attributes array The custom attributes for a sidebar ['itemscope' => 'itemscope', 'itemtype' => 'http://www.schema.org/WPSideBar']
sidebars array An array with the sidebar names as values []

 

Social

Displays a selection of social icons, linking to social profiles

Property Type Description Default Values
color_background boolean If the icons should have a background true
hover_item string The optional hover.css class applied to each social button. For this to work, hover should also be set to true while booting the instance. ''
icons array The default font awesome icons for each network See below
urls array The urls to profiles, in the format 'network' => 'url', e.g. ['facebook' => 'http://www.facebook.com/profile/'] []
titles array Optional titles, displayed next to the icons, in the format 'network' => 'title', e.g. ['facebook' => 'Facebook'] []

Default values for the icons property

    [
        'email'         => 'far fa-envelope', 
        'telephone'     => 'far fa-phone', 
        'facebook'      => 'facebook', 
        'instagram'     => 'fab fa-instagram', 
        'twitter'       => 'fab fa-twitter', 
        'linkedin'      => 'fab fa-linkedin', 
        'google-plus'   => 'fab fa-google-plus', 
        'youtube'       => 'fab fa-youtube-play', 
        'pinterest'     => 'fab fa-pinterest', 
        'dribbble'      => 'fab fa-dribbble',
        'behance'       => 'fab fa-behance',
        'reddit'        => 'fab fa-reddit-alien', 
        'stumbleupon'   => 'fab fa-stumbleupon',
        'whatsapp'      => 'fab fa-whatsapp'
    ]

 

String

Echoes a string

Property Type Description Default Values
string string The string you want to echo ''

 

Tabs

Displays a tabs component.

Property Type Description Default Values
hover_item string The optional hover.css class applied to each tab. For this to work, hover should also be set to true while booting the instance. ''
position string The position of the tabs, either top, right or left 'top'
tabs array The different tabs, with keys as ids and an array with content, icon (as a Font Awesome string), link and title as keys []

Example

This example clarifies how tabs can be set up.

MakeitWorkPress\WP_Components\Build::atom( 'tabs', [
    'position' => 'left',
    'tab'      => [
        'tab_one' => [
            'content' => '<div>' . __('Some Content', 'textdomain') . '</div>', // The content of the tab 
            'icon'    => 'user', // The icon in the tab, in this case the user icon
            'title'   => __('Profile', 'textdomain') // The title of the tab
         ],
        'tab_two' => [
            'icon'    => 'sign-out', // The icon in the tab, in this case the sign-out icon
            'link'    => 'https://www.domain.com/signout/' // This tab will not have content but follow the given url.
            'title'   => __('Sign Out', 'textdomain') // The title of the tab
         ],
    ]
] )

 

Termlist

Displays a list of terms associated with a certain post.

Property Type Description Default Values
id int The post ID for the termlist get_the_ID()
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
taxonomies array The taxonomies to load the termlist for. See the example for the format. If this value is empty, it will automatically load the terms for each taxonomy associated with a post []

Example

This example shows how taxonomies may be defined.

MakeitWorkPress\WP_Components\Build::atom( 'termlist', [
    'id'           => 6, // The post ID is going to be 6
    'taxonomies'   => [
        // We display terms from the category taxonomy
        'category' => [
            'after'   => '', // Custom content after the terms
            'before'  => '', // Custom content before the terms
            'icon'    => 'far fa-folder' // The icon in front of the terms
            'seperator' => ',' // The category terms are seperated by comma
         ],
        // And we display terms from the post_tag taxonomy
        'post_tag' => [
            'after'   => '', // Custom content after the terms
            'before'  => '', // Custom content before the terms
            'icon'    => 'tags' // The icon in front of the terms
            'seperator' => ',' // The tags are seperated by comma
         ],
    ]
] )

 

Terms

Displays terms from a given taxonomy, either styled normally or as buttons. Each term displayed will link to it's term archive and have a data-id attribute returning the term id. By default, shows all post tags.

Property Type Description Default Values
after string The content after each term ''
args array The arguments for get_terms ['taxonomy' => 'post_tag']
before string The content before each term ''
hover_item string The optional hover.css class applied to each social button. For this to work, hover should also be set to true while booting the instance. ''
seperator string The seperator between each term '/'
terms array An optional custom array of terms []
term_style string The style for displaying the terms, either 'normal' or 'button' 'normal'

 

Title

Displays a post title

Property Type Description Default Values
attributes array Custom attributes for the post title ['itemprop' => 'name']
link string An optional link, where the title may link to ''
schema boolean Whether to display Microdata or not. Also removes schematic attributes. true
tag string The tag used for displaying the title 'h1'
title string The actual title get_the_title()

 

Type

Displays the label or name for the current post type

Property Type Description Default Values
name string Optional name that is displayed ''
type string The post type of the current post get_post_type()

 

Video

Displays a video

Property Type Description Default Values
attributes string The custom attributes for a video. ['itemprop' => 'video']
date string The structured data uploadDate for the video. ''
description string The structured data description for the video. ''
name string The structured data name for the video. ''
placer string The default class that is used to make the video response, assuming a 16:9 video. 'atom-video-placer'
schema boolean Whether to display structured data or not. Also removes schematic attributes. true
thumbnail string The URL to the thumbnail of the video. ''
video string The embed code, html5 video or src (URL) to a video. ''
video_height int A custom height for the video. Applies if the video property is an URL. ''
video_width int A custom width for the video. Applies if the video property is an url. ''