Web Components

Introduced by Alex Rusell at the Fronteers Conference in 2011, Web Components have since gained traction among web developers to create encapsulated and reusable elements for the web.

They look like that:

<my-component name="Dennis"/>

As you can see, it's not much different than your normal HTML element like a div or li. Since web components are built with Javascript, they are executed on the client side, so when visited in a browser. A custom component could be programmed in any way, depending on it's purpose.

For example, the goal could be to create a card component that displays the 'name' attribute once executed:

							
							<my-card name="Dennis">
								<div class="card-wrap">
									<h1 class="card-title">Dennis</h1>
								</div>
							</my-card>
							
						

Components behave like normal HTML elements, so you can target them by using CSS:

							
							my-card {
								background: white;
								padding: 1em;
								border-radius: 0.125em;
							}
							
						

That's it for the most part, let's dive deeper into how spx is utilizing the power of web components. 🦾

Attributes

All settings for spx components are applied using attributes. These are no different to attributes for standard HTML elements.

							
							<spx-masonry
									columns="4"
									bp-columns="1000:2,600:1"
									gap="2%">
								<img src="img.jpg"/>
								<img src="img2.jpg"/>
								<img src="img3.jpg"/>
								...
							</spx-masonry>
							
						

The above code would output a masonry layout of images that spans 4 columns, with a gap of 2% between the images. The number of columns will reduce to 2 when the screen size is under 1000px and to 1 when under 600px.

Every component has different possible attributes that can be applied. Please head to the individual components to find out more.

CSS variables

Components which are not purely functional can also be styled using CSS variables. Here, the variable names correlate with their attribute counterpart like this:

							
							:root {
								--spx-masonry-gap: 10px;
							}
							
						

This would create a gap of 10px between all images of all existing masonry components on the site. If you want to target a specific instance, you could give an ID or class to the component:

							
							<spx-masonry
									id="my-masonry">
								<img src="img.jpg"/>
								<img src="img2.jpg"/>
								<img src="img3.jpg"/>
								...
							</spx-masonry>
							
						

							
							#my-masonry {
								--spx-masonry-gap: 1em;
							}
							
						

Helper functions

While many of the components will work without WordPress, the true, time-saving power of spx comes from using it in conjunction with the provided PHP helper functions. At the moment, helper functions exist for the masonry and navigation component. In fact, the navigation component only works using the helper function.

							
								<?php $images = spx\get::acfGallery("myGallery") ?>
							
						

							
							<spx-masonry images="<?php echo $images ?>"/>
							
						

This will automatically create a masonry layout from the ACF gallery! We are hard at work to add more helper function for other frameworks like Metabox.

Slots

Some components have certain slots that can be filled with custom markup. For example, the accordion can be filled with custom slots for the header and content.

							
							<spx-accordion>
								<div slot="header">Click me to unveil the content</div>
								<img slot="content" src="image.jpg"/>
							</spx-accordion>
							
						

Events

Javascript events are being emitted by a couple of components. You can attach an event listener to those just like you normally would.

							
                            document.addEventListener('spxEditButtonSave', function() {
                                // your functions
                            }
							
						

Methods

Components might expose public methods in Javascript:

							
                            (async () => {
                                await customElements.whenDefined('spx-typewriter');
                                const sT = document.querySelector('spx-typewriter');
                                await sT.play();
                            })();
							
						

The above code would start the animation of the typewriter component. Methods come in handy when trying to interact with other libraries or your own functions.

			                <spx-accordion/>

Attributes

Slots

			                <spx-animate/>

Attributes

			                <spx-class-toggle/>

Attributes

			                <spx-edit-button/>

At the moment, only text fields that are coming from Advanced Custom Fields and wp_options can be updated. We are working hard to support more frameworks and options in the future.

To enable front-end editing, just add the spx-edit-button component to a page. After that, you have to mark all elements that you want to be editable on the site. This is being done by adding the data-spx-edit attribute to existing text elements:

							
							<h1 data-spx-edit="myTextField" type="acf">
								Some text that you want to be editable.
							</h1>
							
		

The wp_options or ACF field name has to be the value of the attribute. After that, you're good to go! Of course, it makes sense to only show to logged in users, so you can wrap it in a condition of your choice.

Please note: to reduce server load, all data is being collected before being sent off. This way, only one AJAX request is needed, even when 100 fields are being updated at the same time. This has the disadvantage that it currently isn't possible to edit different types of fields with one button. For example, you can't mix wp_options and ACF fields since they need a different function to update the data in the request.

However, it is possible to have multiple spx-edit-button on the page, each having different targets:

			
<h1 data-spx-edit="myTextField" data-spx-edit-id="my-acf-fields">
    Some ACF field that you want to be editable.
</h1>
<spx-edit-button edit-id="my-acf-fields" type="acf"/>

<h1 data-spx-edit="blogdescription" data-spx-edit-id="my-option-fields">
    The blog tagline.
</h1>
<spx-edit-button edit-id="my-option-fields" type="option"/>
			
		

Attributes

Events

			                <spx-iframe/>

Attributes

			                <spx-image-comparison/>

Attributes

			                <spx-group/>

Attributes

			                <spx-lightbox/>

Open the frame in a new window to see it working correctly.

The component will automatically wrap all inner elements with an <a> element, so you don't need to change your existing markup:

			
			<spx-lightbox>
				<img src="img.jpg"/>
				<img src="img2.jpg"/>
				<img src="img3.jpg"/>
			</spx-lightbox>
			
		

Attributes

			                <spx-masonry/>

It is possible to nest the masonry component inside a lightbox to create an overlay gallery for all images.

Attributes

                <?php spx\get::gallery($fieldName, $type) ?>

			                <spx-mockup/>

Attributes

			                <spx-navigation/>

Attributes

				<?php spx\get::navigation("myMenu") ?>

Events

			                <spx-offset/>

Attributes

			                <spx-scrollspy/>

To make this component work correctly, the href attributes of the links hav to correlate with the IDs of the sections and links must be wrapped with a li tag:

							
                            <ul>
                                <li><a href="#section1">Section 1</a></li>
                                <li><a href="#section2">Section 2</a></li>
                            </ul>
                            <div id="section1"><div>
                            <div id="section2"><div>
							
						

Attributes

			                <spx-share/>

Attributes

			                <spx-snackbar/>

You have probably seen and used Snackbars all over the internet. As success, error or information bars. Creating a Snackbar with the Oxygen element is easy, simply wrap the element you wish to trigger the Snackbar with and it's good to go!

Attributes

			                <spx-typewriter/>

The classic reveal. This component needs an inner text element (heading or text) to work. Please note that the text is being taken from the field in the settings, as the inner content of the text element is being ignored here.

Attributes

Methods