ClassicPress Blog

Posted on September 12, 2019September 12, 2019 by John Alarcon | Category: Tutorials

A static dashboard widget is a great way to share information, important links, or action items with your clients when you hand-off a site. Very little code – very high user impact!

When handing off a ClassicPress website to a client, do you provide them with information or links to get them off to a good start? A static widget in the dashboard – just like the one pictured below – is a great solution for this! Wouldn’t it be cool to add something like this to the client’s dashboard? Well, we’re going to build it shortly.

Depiction of a Static Text Widget

The image above depicts what we’ll be creating here today. However, before moving on, let’s make a few quick distinctions about widgets, shall we?

Static Widgets vs Dynamic Widgets

Whereas a dynamic widget shows content that changes over time, such as latest posts or recent comments, a static widget shows the same content always. In the image above, the widget is simply inviting the user (ie, your client) to contact their project manager.

Of course, this is just a simple example of how you might use a static widget. Indeed, you might want to include your business address, hours of operation, helpful links, payment info, or any of those other things that you might typically include in a hand-off document.

Dashboard Widgets vs Front-end Widgets

One last distinction to make before starting this project is the difference between dashboard widgets and front-end widgets. It’s simple, but, bears repeating.

Dashboard widgets will appear in the main dashboard view. The site admin can collapse and expand the widget, as well as move it to a new position, or even hide it altogether.

Front-end widgets are those that are displayed to visitors on your site. Visitors cannot usually expand or collapse front-end widgets (although there are exceptions,) but, they will not likely be able to move or hide the widget content.

Where to Place the Code?

If you’re coming from the WordPress space, you will be familiar with placing code into your theme’s functions.php file. This is the “old school, quick ‘n dirty” way, and is no longer recommended. The code in this tutorial should be placed into a utility plugin. If your site already has a utility plugin, great, you can just add the code below to that plugin. If you don’t yet have such a plugin, go build one. I’ll wait for you here.

The Process of Creating a Static Widget

To create a dashboard widget, three objectives must be achieved. The three objectives are to:

1. create a function that prints the widget content, and
2. create a function that registers the new widget in the system, and
3. use an action hook to specify when the widget should be registered.

Let’s work through these objectives now. Move through the following steps, adding the code examples to your utility plugin. There’s no need to make customizations as you go – let’s just get it working first and fine-tune later.

1. Print the Widget Content

This simple function populates the widget with your content. As you can see, PHP tags are used in the function to allow for neater HTML markup. Add the code to your utility plugin.

2. Register the New Widget

This function registers the widget in the system by calling the wp_add_dashboard_widget function with several arguments. These arguments tell the system your preferred id and title for the widget, as well as the name of the function that will ultimately output the widget content (from step 1 above.) Add the code to your utility plugin.

3. Hook the New Widget in at the Right Time

In case you didn’t notice, those functions created in Steps 1 & 2 aren’t actually called anywhere. Yet. If they aren’t called, they can’t run. That’s where an action hook comes into play. The action hook tells the system exactly when to run the function that registers your widget, which, in turn, tells the system which function to use to display the content. Now, that was a lot of words, but, it really just boils down to a single line of code that says “run this function during the wp_dashboard_setup action.” Add the line to your utility plugin.

Verify your Work

With the above objectives out of the way, take a moment to verify your work. Head over to the dashboard and find that you now have a new widget showing in all its glory. Collapse it. Expand it. Move it around. Hide it. It should work just like every other widget in the dashboard.

Initial Static Text Widget

Add Meaningful Content

With the widget now displaying in the dashboard, you can revisit the display function (from Step 1) and flesh it out with whatever content you like. In the final example below, I’ve combined the code from above and added some additional markup to make the widget look like the original example image.

Extra Credit

The example above will show the widget to anyone who has access to the main dashboard. Can you think of a way to show the widget to only admin users? Or, how about limiting it to just a single user? I think you can figure it out!

Wrapping Up

Adding a static widget to the ClassicPress dashboard is actually quite easy. There’s no need to add a whole plugin just to show some information in the dashboard. With very little work, you can create your own great-looking dashboard widgets and show your clients that their site is on your mind. Add text, links, images – or anything else that might be helpful to your clients!

What do you think?

Did you realize dashboard widgets were so easy to create? Have you been using a plugin and are going to switch to this method instead? What other things might you include in a dashboard widget? I’d love to hear your thoughts – let me know in the comments!

This tutorial has been provided by John Alarcon and was originally published on CodePotent.com. The original post can be found here.

Posted on September 4, 2019September 2, 2019 by John Alarcon | Category: Tutorials

A beginner’s guide to converting procedural PHP into namespaced or object-oriented PHP – with a very understandable apples-to-apples comparison! This will be a primer for a more in-depth article on using namespacing in ClassicPress plugins.

The Tutorial

If you’re like most, you will have searched the web and found code-snips for your ClassicPress website. Let’s say you wanted to change the footer text in the dashboard. After a quick search, you find the following code-snip with instructions to place it into your theme’s functions.php file.

First off, code-snips should go into a utility plugin, rather than your theme’s functions.php file. This is achieved by adding a short comment at the top. Additionally, the function name is prefixed to prevent code collisions. Here’s what that looks like.

Great! The code-snip is now held safely in a utility plugin that can be activated and deactivated in your dashboard. The above example is written in basic, procedural PHP and, because the function name has a prefix, it is nicely isolated from clashing with other code in the system.

Prefixing your code in this way is usually enough to prevent collisions, so, if that’s all you’re after, you can stop here. However, also note that, as you find new code snips, you can add them to this same utility plugin; there’s no need to create another. Now, git ta steppin’, … the rest of us want to namespace this thing! So, let’s!

As you can see, the big difference is that the prefix is used in the namespace instead of the function name, and the __NAMESPACE__ magic constant is used when hooking the function into ClassicPress. This is handy when your plugin grows to contain a lot of functions; you can change the namespace in one single place, instead of changing a bunch of prefixes. Namespacing is the actual built-in PHP method for isolating, or encapsulating, our code, but, more often, you’ll see code being encapsulated with object-oriented PHP. Here’s that same code-snip as an object-oriented plugin.

In the case of object-oriented PHP, you can simply use the __construct() (or similar initialization) method to hold your action and filter hooks. I quite like this style of keeping all the actions and filters together and is the method I tend to use most. And, the $this variable is extremely handy when you want to pass data back and forth between the various methods (functions) inside the class.

Wrapping Up

As you can see, a code-snip can be added to your ClassicPress site without having to add it to your theme’s functions.php file. Placing your code-snips into a utility plugin is a better practice and gives you a quick means of activating and deactivating all of them quickly. And, of course, there are various ways to encapsulate our code and achieve the exact same result. There’s no requirement to use one method or another. You decide. As long as you have at least used unique prefixes, as shown in the first plugin example, you can be reasonably sure your code will be safe from collisions…and safe from theme changes, too!

What do you think?

Was it helpful to see a simple code-snip converted into a plugin? Did it answer any questions to see that plugin converted into other styles of code? Do you have a preference over which style to write your code? I’m curious to hear your thoughts – let me know in the comments!

Note: the header comment used in the examples here was very basic. There are more fields that can be used.

This tutorial has been provided by John Alarcon and was originally published on CodePotent.com. The original post can be found here.

Posted on June 27, 2019August 27, 2019 by Patrick Klein | Category: Tutorials

When performing changes to your theme, like changing up the template; adding functionality; or adding CSS, it is often advised to use a child theme. But how do you make a child theme? What even is a child theme? Why do you need this? All questions that people new to this level of ClassicPress will come up against. This tutorial will do its best to answer these questions in the easiest way possible.

What is a child theme?

Simply said, a child theme is a theme that is dependent on another theme. The theme that the child theme is dependent on is called the parent theme. The child theme will pull its code from the parent theme to fill in any gaps. This will make it appear as if you’re using the parent theme.

So why use a child theme?

In the child theme you can overwrite templates, functions and CSS from the parent theme without actually changing the parent theme. This means that when you update the parent theme, these changes will remain in effect. So, you can safely make all the template, styling and functionality changes to a theme that you want, without having updates overwrite your efforts.

How do I make a child theme?

By now you should be convinced that if you are going to make changes to a theme, you should get a child theme. So let’s make one step by step.

What do I need?

• Access to your ClassicPress files, either through FTP or a file manager.
• A parent theme of your choosing. For this tutorial we will use Twenty Seventeen
• A code/text editor.

The Tutorial

Step 1: Open your ClassicPress installation in FTP or a file manager and Navigate to wp-content > themes.

Step 2: Create a new folder and access it. The name does not really matter, but for future reference, it is easiest to name this folder <themename>-child. So in this case it will be twentyseventeen-child.

Step 3: Create a file named style.css in the new folder and open it in an editor.

Step 4: Next we are going to create some theme details. Like below:

• Theme Name => Your chosen theme name
• Theme URL => Your URL
• Description => A short description of the child theme
• Author => Your name
• Author URL => Your domain
• Template => The folder name of your parent theme, in this case twentyseventeen, but this is different for each theme.
• Text-domain => The folder name of your child theme, in this case twentyseventeen-child.

Note: Only Theme Name and Template are required, the rest is optional.

Now add these details to the style.css you created like below and save the file.

/*
Theme Name: Twenty Seventeen Child
Theme URL: https://www.classicpress.net/
Description: Example of a Child theme for Twenty Seventeen
Author: klein
Author URL: https://forums.classicpress.net/u/klein
Template: twentyseventeen
Text Domain: twentyseventeen-child
*/
/* You can add custom CSS below */
 

Step 5: Create a file named functions.php in the child theme folder and open it in an editor.

Step 6: Add the following code to the functions.php file and save it.

<?php
//Enqueue parent theme css
add_action( ‘wp_enqueue_scripts’, ‘enqueue_parent_theme_css’ );
function enqueue_parent_theme_css() {
wp_enqueue_style( ‘parent-style’, get_template_directory_uri().’/style.css’ );
}
//Add custom functions below
?>

Step 7: Go to your ClassicPress admin area and go to themes. When here, ‘Activate‘ the child theme.

Step 8: Your child theme is ready for use!

How do I start making changes?

Now that your child theme is ready for use, you obviously want to start making changes. As mentioned before, there are three main uses for your child theme: change styling, add functionality and edit templates. Doing these three things is easy!

Changing styles

To overwrite your theme’s CSS, simply go to the style.css file you made during the creation of this child theme. Add the CSS changes you want to this file below the details and save them!

Note: The child theme styles are rendered after the parent, so anything you add here will overwrite the specifications made in the parent’s style.css file.

Adding functionality

Often when you are trying to add functionality through snippets, you will be instructed to add them to your theme’s functions.php. It works the same way with a child theme. You can add these snippets or write your own in the functions.php file you made during the creation of this child theme. Just add them below the enqueue_parent_theme_css function.

Editing templates

To edit a template file you must first find the file in your parent theme. For example single.php, sidebar.php, footer.php, etc. When you have found the file you want to edit, make a copy and upload this copy to your child theme. Be careful to keep the URL structure intact! For example, if you found a file in the folder template-parts, make sure it’s also placed in a folder named template-parts in your child theme.

Some plugins also gives you the option to edit their templates in your child theme! An example of this is WooCommerce. To do this, you go to your plugin folder and look in the templates folder. Copy the file you want to edit. When in your child theme, make a folder with the same name as the plugin’s folder (This folder takes the place of templates in your URL structure) and add the copy of the file you wish to edit to this folder. Also make sure the URL structure stays intact from here, just like a theme file.

Note: Because the plugin folder in your child theme takes the place of templates, you do not need to add a templates folder in these plugin folders.