-
Notifications
You must be signed in to change notification settings - Fork 4
Molecules
Michiel Tramper edited this page Mar 24, 2022
·
20 revisions
A molecule is a modular component or section of a website, such as a footer, header or grid of posts.
Each molecule has unique properties, besides the common properties you may give to each molecule. These are listed here. These properties also have default values.
Contrary to an atom, a molecule may contain several atoms inside itself. This is where the real power of a molecule lays, as you can display any of the atoms inside a molecule.
A set of properties is defined while rendering an atom in the following way:
MakeitWorkPress\WP_Components\Build::molecule( string $moleculename, 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 a site header, which is fixed to the top and displays a logo and menu atom.
MakeitWorkPress\WP_Components\Build::molecule(
'header',
[
'atoms' => [
'logo' => [
'atom' => 'logo',
'properties' => [
'default' => ['src' => 'http://www.url.com/logo.jpg', 'height' => 80, 'width' => 240]
]
],
'menu' => [
'atom' => 'menu',
'properties' => ['args' => ['theme_location' => 'main']]
]
],
'fixed' => true
]
);There is also a shorter function available:
wpc_molecule(
'header',
[
'atoms' => [
'logo' => [
'atom' => 'logo',
'properties' => [
'default' => ['src' => 'http://www.url.com/logo.jpg', 'height' => 80, 'width' => 240]
]
],
'menu' => [
'atom' => 'menu',
'properties' => ['args' => ['theme_location' => 'main']]
]
],
'fixed' => true
]
);If a molecule supports to render atoms, they are often a property of that molecule. They are always formatted in the following way:
[
'key_for_atom' => [
'atom' => string $atomname, // The name of the atom
'properties' => array $atomproperties // The properties for the given atom
]
]To see this in action, please look to the example of the site header above.
Displays a site footer, usually the bottom part of a website. The footer consists of one section which may display the sidebar, and a lower socket section with can contain several atoms.
| Property | Type | Description | Default Values |
|---|---|---|---|
| attributes | array | The custom properties for the footer | ['itemscope' => 'itemscope', 'itemtype' => 'http://schema.org/WPFooter'] |
| atoms | array | The atoms displayed in the socket. See rendering atoms. | [] |
| container | boolean | Whether the footer's content should be contained inside a container or be full-width | true |
| grid_gap | string | The optional grid gap between the sidebars. Supports 'tiny', 'small', 'default', 'medium', 'large', 'huge' and 'none', |
'default' |
| sidebars | array | Contains an array of sidebars, with sidebar names/ids as keys and grid classes as values. Grid classes support the grid classes as provided by WP Components. These are 'full', 'half', 'third', 'two-third', 'fourth', 'three-fourth' and 'fifth'. Also, see the example below. |
[] |
| video | string | Accepts the complete URL of a video, which will be displayed as a video background. | '' |
The following displays a footer with two sidebars and a socket with a copyright message floating left and a menu floating right.
MakeitWorkPress\WP_Components\Build::molecule(
'footer',
[
'atoms' => [
'copyright' => [
'atom' => 'copyright',
'properties' => ['float' => 'left', 'name' => 'Organization Name']
],
'menu' => [
'atom' => 'menu',
'properties' => ['args' => ['theme_location' => 'footer'], 'float' => 'right']
]
],
'sidebars' => [
'footer_one' => 'components-half-grid',
'footer_two' => 'components-half-grid'
]
]
);
Displays a site header
| Property | Type | Description | Default Values |
|---|---|---|---|
| atoms | array | The atoms displayed in the middle part of the header. See rendering atoms. | [] |
| attributes | array | The custom properties for the header | ['class' => 'molecule-header-top', 'itemscope' => 'itemscope', 'itemtype' => 'http://schema.org/WPHeader'] |
| container | boolean | Whether the header's content should be contained inside a container or be full-width | true |
| fixed | boolean | Whether the header should stick to the top or not. | true |
| headroom | boolean | If the header should hide when scrolling down, and display when scrolling up. | false |
| shrink | boolean | If the header should shrink when scrolling down | false |
| socket_atoms | array | The atoms displayed in the bottom part of the header. See rendering atoms. | [] |
| top_atoms | array | The atoms displayed in the top part of the header. See rendering atoms. | [] |
| transparent | boolean | Whether the header should be transparent or not. | false |
| video | string | Accepts the complete URL of a video, which will be displayed as a video background. | '' |
Displays a fullwidth section, containing any possible atom or columns.
| Property | Type | Description | Default Values |
|---|---|---|---|
| atoms | array | The atoms that are displayed in the section See rendering atoms. | [] |
| columns | array | Columns to display with their corresponding width and containing atoms or molecules. Use ['column' => 'half', 'atoms' => [['atom' => 'atom']]]
|
[] |
| container | boolean | Whether the post footer's content should be contained inside a container or be full-width | true |
| custom_action | string | Adds a dynamic custom action hook in four places of this section. Named respectively 'components_{$custom_action}before', components{$custom_action}container_begin', components{$custom_action}container_end', components{$custom_action}_after' Will be sanitized. | '' |
| grid | boolean | Whether to display a grid or not | false |
| grid_gap | string | The grid-gap for the enabled grid. Supports 'none', 'tiny', 'small', 'medium', 'large', 'huge' or 'default'
|
```'default'`` |
| molecules | array | The optional molecules that are displayed in the section. | [] |
| scroll | boolean | Whether to show a scroll down button at the bottom of the post header or not | false |
| tag | string | The default HTML tag to display this section in | 'section' |
| video | string | Accepts the complete URL of a video, which will be displayed as a video background. | '' |
The Post Header and Post Footer are deprecated. Use the section molecule instead.
Display a grid or list of posts
| Property | Type | Description | Default Values |
|---|---|---|---|
| ajax | boolean | Whether to load paginated posts through ajax or not. | true |
| attributes | array | The custom attributes for posts. | See below |
| grid_gap | string | The optional grid gap between the various posts. Supports 'tiny', 'small', 'default', 'medium', 'large', 'huge' and 'none', |
'default' |
| infinite | boolean | Whether to load consecutive post pages through infinite scrolling or not | false |
| pagination | array | The arguments for the pagination atom. | ['type' => 'numbers'] |
| post_properties | array | The properties for each post in the grid. | See below |
| query | object | A WP_Query object containing the wanted posts | '' |
| query_args | array | The arguments for querying a post, based upon the WP_Query class | [] |
| schema | boolean | Whether to display Microdata or not. Also removes schematic attributes. | true |
| view | string | The style of the grids. Accepts list, grid or a custom class | 'list' |
| wrapper | string | Custom class for the wrapper around posts | '' |
The following values are the default values for the attributes property
[
'data' => ['id' => 'molecule-posts'], // Used to match requests for ajax. Should be unique
'itemscope' => 'itemscope',
'itemtype' => 'http://schema.org/Blog'
]The following values are the default values for the postProperties property. This property determines how each of the posts looks like in the grid.
[
// The attributes for each post
'attributes' => [
'itemprop' => 'blogPost',
'itemscope' => 'itemscope',
'itemtype' => 'http://schema.org/BlogPosting'
],
// Indicates if we put author and other schema.org data within a blog bost
'blog_schema' => true,
// Accepts a set of atoms for within the content
'content_atoms' => [
'content' => [
'atom' => 'content',
'properties' => ['type' => 'excerpt']
]
],
// Accepts a set of atoms for use in the post footer
'footer_atoms' => [
'button' => [
'atom' => 'button',
'properties' => ['float' => 'right', 'label' => __('View post', 'components'), 'link' => 'post', 'size' => 'small']
]
],
// The default grid. Accepts 'full', 'half', 'third', 'fourth', 'fifth' or an array with a pattern of these
'grid' => '',
// Accepts a set of atoms for use in the post header
'header_atoms' => [
'title' => [
'atom' => 'title',
'properties' => ['attributes' => ['itemprop' => 'name headline', 'class' => 'entry-title'], 'tag' => 'h2', 'link' => 'post' ]
]
],
// The post image
'image' => [ 'link' => 'post', 'size' => 'medium', 'enlarge' => true ],
// The logo that is used in microschemes and rich snippets
'logo' => 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==',
// The name of the organization that is used in microschemes and rich snippets
'organization' => get_bloginfo('name')
]
Displays a common section
| Property | Type | Description | Default Values |
|---|---|---|---|
| atoms | array | The atoms displayed in the section. See rendering atoms. | [] |
| columns | array | Columns to display with their corresponding width and containing atoms. Use ['column' => 'half', 'atoms' => 'atom' => 'atom'] | [] |
| container | boolean | Whether the section's content should be contained inside a container or be full-width | true |
| grid | boolean | Whether the section's content can be displayed in a grid | false |
| grid_gap | string | The gap between items within the grid | 'default' |
| molecules | array | The molecules displayed in the section. Works similar as rendering atoms, but you can specify molecules now. | [] |
| tag | string | The tag used to display the section | 'section' |
| video | string | Accepts the complete URL of a video, which will be displayed as a video background. | '' |
Displays a section with video background and one column with a string atom.
wpc_molecule( 'section', [
'columns' => [
[
'column' => 'full',
'atoms' => [
'string' => ['atom' => 'string', 'properties' => ['string' => 'Column!']]
]
]
],
'grid' => true,
'height' => 'normal',
'video' => 'https://teenstreet.life/wp-content/uploads/2020/07/ts-opening-video-compressed.mp4'
] );
Displays a slider with custom slide content based upon Tinyslider
| Property | Type | Description | Default Values |
|---|---|---|---|
| attributes | array | The custom attributes for posts. | ['data' => ['id' => uniqid()]] |
| options | array | The Tinyslider options for the slider | See below |
| scroll | boolean | Adds a scroll button to the bottom of the slider. | false |
| slides | array | The actual slides, an array with video, image, atoms and attributes keys. See the example below. | [] |
| thumbnail_size | string | The default size for thumbnails, such as 'thumbnail'. If set, thumbnail navigation is added to the slides. Slides should have an image in the form of attachment IDs. | '' |
These are the default values for the options property. These options reflect the properties as they are supported by Tinyslider
[
'arrowKeys' => true,
'autoHeight' => true,
'controlsText' => ['<i class="fa fa-angle-left"></i>', '<i class="fa fa-angle-right"></i>'],
'navPosition' => 'bottom',
'mode' => 'carousel', // Type of animation
'speed' => 500, // Speed of animation
]This example renders a slider with three slides, once with an image and a white background, one with a video and one with a description and button atom
MakeitWorkPress\WP_Components\Build::molecule(
'slider',
[
'slides' => [
'slider_one' => [
'attributes' => ['background' => '#FFFFFF', 'class' => 'slider-one'],
'image' => ['image' => 71] // These can be the properties for an image atom
],
'slider_two' => [
'video' => ['video' => 'http://v.io/v.mp4'] // These can be the propertyies for a video atom
],
'slider_three' => [
'attributes' => ['background' => '#FFFFFF', 'class' => 'slider-three'],
'atoms' => [
'description' => ['atom' => 'description', 'properties' => ['description' => 'Description']]
'button' => ['atom' => 'button', 'properties' => ['label' => 'Label']]
]
]
]
]
);The following shows a slider with two large images and thumbnail navigation. This navigation has the same images but in thumbnail size.
MakeitWorkPress\WP_Components\Build::molecule(
'slider',
[
'slides' => [
'slider_one' => [
'image' => ['image' => 71, 'size' => 'large'] // These can be the properties for an image atom
],
'slider_two' => [
'image' => ['image' => 71, 'size' => 'large'] // These can be the properties for an image atom
],
],
'thumbnailSize' => 'thumbnail'
]
);