Email overrides

One of the most common brand identity questions are related to the design of emails that have been generated by PeepSo and dispatched to web server to send them to end user.
These emails are by default very minimalistic and contain only basic information.

So how to change the color scheme, maybe add an image to reflect your brand?
The solutions are rather simple, but require a basic knowledge of HTML and CSS so you can actually design your email templates.

Solution 1; Backend Configuration

PeepSo allows for complete change of the email HTML template in the backend configuration.
Go to WP Admin -> PeepSo -> Configuration -> Notifications and scroll down to the “Emails” section until you find the options to override an entire HTML

Simply copy and paste your custom email HTML into the “Override entire HTML” box and emails created with PeepSo will follow your new design.

Solution 2; Template override

We already wrote about template overrides and how they work, so we won’t try to re-invent the wheel one more time.
If you’re not sure how template overrides work, we strongly suggest you to read the documentation about it. It can apply to any other PeepSo template not just emails, and can really be a little extra step that you have to do to give your site a personal touch or unique visual identity.

To override the PeepSo-generated emails, copy these three (3) files:

  • ROOT/wp-content/plugins/peepso-core/templates/general/email.php
  • ROOT/wp-content/plugins/peepso-core/templates/general/email-header.php
  • ROOT/wp-content/plugins/peepso-core/templates/general/email-footer.php

Paste these files into ROOT/wp-content/peepso/overrides/templates/general

Since PeepSo 3, folder structure has been changed and the override folder is now called “custom”. Simply use ROOT/wp-content/peepso/custom/templates/general instead.
Note: If override folder structure does not exist, create the needed folders manually.

Once files are copied to the override folder, you can start customizing them to suit your desired visual identity.

Image overrides

Making a community your own has never been easier. PeepSo avatars, profile covers and all other images are great but they are not perfect fit for every community type. What if you could change the default avatars, default covers, and many other default images? Yes, you can. And you can do it in such way to preserve them when you update PeepSo.

Video Tutorial

How to Make This Happen?

It is really simple.

  1. Go to ROOT/wp-content/plugins/peepso-core/assets directory
  2. Copy the folder images and paste it into ROOT/wp-content/peepso/custom/
  3. Start editing files found in ROOT/wp-content/peepso/custom/images
If you use  PeepSo 2 or PeepSo 1, folder structure is slightly different and the override folder is called “overrides”. In step 2, simply use ROOT/wp-content/peepso/overrides instead.
Note: If override folder structure does not exist, create the needed folders manually.

That’s really it.
Please bare in mind though, that you need to preserve the file names and folder structure within newly created override.
If you change the file name, or move the images around from subfolders, they will not work.

Template overrides

This article is for advanced users not afraid to go beyond configuration switches in WordPress backend, but it’s written in such manner that novice users with no previous experience with overrides can easily understand it.

This document will show you how to create overrides for PeepSo templates. This method works on all PeepSo plugins and there are two ways to achieve this customization. We will explain them both, but before proceeding, you will need to know few things.

  • Every PeepSo plugin have templates directory where templates that show the functionalities are stored. This is how most well-coded WordPress plugins work to ensure maximum compatibility with almost any theme you can imagine, and this is why PeepSo is out of the box compatible with so many WordPress themes.
  • We sometimes update our template files to accommodate new features or fix bugs. There is no way to add new feature if we don’t show it through template file, and to show it, template file must be updated. This may lead to discrepancy in features because if you modify the template file that has the new feature in newest version, then you must update your override file to actually see this new feature.

How to Find The Right File to Override?

This can be daunting task if you’re not familiar with theme overrides, but once you understand the fundamentals, it becomes ridiculously easy.
We already mentioned every PeepSo plugin have templates directory where it stores the template files.

Lets try together, to find the right file which will allow us to modify the cover area in the profile

Depending on what browser you use, this first step might be different, but only in the way it’s presented. The logic behind it is absolutely the same.
We are using Firefox Developer Edition in this exercise, but you can use any browser that have Inspector tools built in.

Right click on the area you want to change and click “Inspect Element”

Once clicked, the following screen will show up, highlighting the entire area you chose with the right click

Our browser did half of the job already. We see that this particular div is styled through ps-focus js-focus ps-js-focus ps-js-focus–1 selectors.

Now lets fire up our favorite code editor and search the template files for this selectors.

We are using Brackets but you can use any editor of your choice as long as it has Find in files option

Search with Find -> Find in files option with this query

<div class=”ps-focus

The search yielded some results

Lets analyze the result.
There are 51 matches in 5 files. So we already narrowed down our search to 5 files.
Do we need to edit the file which shows the content when user has no access? Nope? Not really.
How about profile options or profile menu? Nope. Group header? Heck no…
So we are down to the “focus.php” which looks most suspicious. And yes, you are right, that is the correct file to override.
We will us it as an example in further exercises.

Template Overrides Within Current Theme

This is probably the most common way to override the PeepSo template files

Continuing our exercise with focus.php copy it from:

ROOT/wp-content/plugins/peepso-core/templates/profile

to

ROOT/wp-content/themes/YOUR-THEME/peepso/profile

Template Override Within PeepSo Overrides Folder

Alternatively, you can use PeepSo overrides folder to copy the focus.php from

ROOT/wp-content/plugins/peepso-core/templates/profile

to

PeepSo 2.x: ROOT/wp-content/peepso/overrides/templates/profile
PeepSo 3.x: ROOT/wp-content/peepso/custom/templates/profile

Note: if this is your first time creating overrides, these folders may not exist and you’ll have to create them manually

CSS overrides

When we designed PeepSo, we wanted to be sure that it always looked great. So we gave it a completely consistent look. Whatever theme you’re using, you’ll get PeepSo exactly the way we designed it.

However, we understand that people want to customize PeepSo, perhaps to tweak the colors so that they better match a theme.

There are several ways to achieve this customization. This article describes them all.

PeepSo custom.css Within A Current Theme

If you want to do overrides this way, the CSS file should be placed in the /peepso/ directory in the parent directory of your WordPress theme or /peepso3/ directory if you’re using PeepSo 3.x

Example:

PeepSo 2.x: ROOT/wp-content/themes/YOUR_THEME/peepso/
PeepSo 3.x: ROOT/wp-content/themes/YOUR_THEME/peepso3/

Inside that directory place the “custom.css” file.
It is absolutely required that file must be named “custom.css

Final custom.css override path is:

PeepSo 2.x: ROOT/wp-content/themes/YOUR_THEME/peepso/custom.css
PeepSo 3.x: ROOT/wp-content/themes/YOUR_THEME/peepso3/custom.css 

Note: Be aware that upgrading the theme might remove this file. So do keep a backup of it and keep it up to date if you want to do overrides that way.

PeepSo style.css Within Content Overrides

Not to worry about losing changes upon upgrading your theme you can also put your override file in the PeepSo overrides directory.

Example:

PeepSo 2.x:ROOT/wp-content/peepso/overrides/css/
PeepSo 3.x: ROOT/wp-content/peepso/custom/css/

Name the file: style.css

The full path to style.css override will be

PeepSo 2.x: ROOT/wp-content/peepso/overrides/css/style.css
PeepSo 3.x: ROOT/wp-content/peepso/custom/css/style.css 

Add The Changes to Additonal CSS Within WordPress Customizer

If you don’t need the full override file, you can always place your changes in Additional CSS box through WordPress Customizer.

Go to WP Admin -> Appearance -> Customize

Every theme should have the panel where you can add Additional CSS

Importance of !important Tag

Sometimes the the CSS override won’t work without !important tag. This is because the way CSS (Cascading Style Sheet) is designed.
Cascading Style Sheets, well, they cascade, and last loaded value is always in effect.

Example:

First loaded CSS file has this class

.div {background-color: black !important;}

Last loaded CSS file has this class

.div {background-color: white;}

If there were no !important tag in the first loaded CSS, the background would be white because value will cascade to the last loaded one. But !important tag forced it to remain black.

With that in mind, if your CSS overrides don’t work, try to force them by adding an !important tag to the values for every parameter.

Example CSS Override File


/*=== TOOLBAR RELATED COLORS ===*/
/* Wrapping PeepSo main menu with all available plugin pages and notifications */
.ps-toolbar {
background-color: #949494;
}
/* Regular link style in desktop toolbar */
.ps-toolbar__menu > span > a,
.ps-toolbar__notifications > span > a {
color: #1B1B1B !important;
}
/* Primary toolbar links on hover */
.ps-toolbar__menu > span > a:hover,
.ps-toolbar__notifications > span > a:hover,
.ps-toolbar__menu > span > a:focus,
.ps-toolbar__notifications > span > a:focus {
background-color: rgba(0,0,0, .05);
}

Text overrides

Have you ever wonder how to change just a little piece of text within PeepSo? We know you are.
Sometimes that pesky “Say whats is on your mind…” in postbox just don’t cut it and you really want to change it to something else. Like “Send the rocket to Jupiter…” or “White House is in Washington…” (we don’t know why would you want to do that but it’s possible)

Plugin translators have been doing just that for decades using translations files.
Stop there. We are aware you don’t need a translation per se, but what is a translation if not a text change?

In this article, we will use PoEdit application for macOS, but the same software is available for Windows and Linux

Once you download and install PoEdit, open the application and select “Create New Translation”


You might be wondering why not selecting “Translate WordPress theme or plugin” and you’re right, it will be easier to do so, but you’ll need paid version of PoEdit to do this, so we’ll stick with “Create New Translation” in this exercise.

The popup window to select the POT file will now be shown.
PeepSo, as is the case with every other decently coded WordPress plugin use POT files to handle all language strings.
Locate the POT file from which you want to change text and open it.
POT files for plugins are always in this location.

ROOT/wp-content/plugins/PLUGIN-NAME/language

Examples:
if you want to change the text in PeepSo Foundation plugin, then the location would be:
– ROOT/wp-content/plugins/peepso-core/language/peepso-core.pot

If you want to translate Groups plugin, then the location would be
– ROOT/wp-content/plugins/peepso-groups/language/groupso.pot

Note: Please be advised that some plugin names have been changed over the course of PeepSo development to better suit or represent the features of a plugin. For example, if you want to translate Chat plugin, it is actually called peepso-messages and it’s language file msgso.pot
To avoid conflicts and having to redo all language files, we didn’t change the POT names.

Once you selected the POT file to modify, PoEdit will ask you what language you want to translate file to.
Assuming you want to change the text for default WordPress language choose the English (United States) as shown in the picture bellow.

Press CMD + F if you’re on Mac or CTRL + F for Windows and Linux to invoke search popup and search for the keyword you want to change. Here we want to change “Say whats is on your mind…” so we will search for keyword “mind“.
Press “Next” until you find it.

In the Translation box, enter your translation for this string

Save the file as peepso-core-en_US.po (remember the location where you save them. We will need these files soon)

Note 1: If you change other files, like picso.pot, friendso.pot or groupso.pot then you need to name them picso-en_US.po, friendso-en_US.po, groupso-en_US.po and so on
Note 2: The file must be saved using po extension. There is no typo here.

PoEdit will now create two files

  1. peepso-core-en_US.po
  2. peepso-core-en_US.mo

Applying the Text Change

Now that we have our files ready, take them both and copy to following location:

ROOT/wp-content/languages/plugins/

If this directory does not exist yet, create it manually

And will you look at that, we just changed the text in the postbox!

Adding More Changes

To add more changes, edit the newly created po file and save to create new mo “translation”

Translating PeepSo

The official translations project for PeepSo is located at Crowdin. If you wish to contribute to existing translations, you can login to Crowdin and join the translators team.

There are, however situations when available translations simply don’t cut it. Maybe you’re not happy with the translation, maybe translation is in formal format when you need the casual one. Don’t worry, you can make your own translations with the little effort.

In this article, we will use PoEdit application for macOS, but the same software is available for Windows and Linux

Once you download and install PoEdit, open the application and select “Create New Translation”

You might be wondering why not selecting “Translate WordPress theme or plugin” and you’re right, it will be easier to do so, but you’ll need paid version of PoEdit to do this, so we’ll stick with “Create New Translation” in this exercise.

The popup window to select the POT file will now be shown.
Locate the POT file you want to translate and open it. POT files for plugins are always in this location.

ROOT/wp-content/plugins/PLUGIN-NAME/language

Examples:
if you want to translate PeepSo Foundation plugin, then the location would be:
– ROOT/wp-content/plugins/peepso-core/language/peepso-core.pot

If you want to translate Groups plugin, then the location would be
– ROOT/wp-content/plugins/peepso-groups/language/groupso.pot

Note: Please be advised that some plugin names have been changed over the course of PeepSo development to better suit or represent the features of a plugin. For example, if you want to translate Chat plugin, it is actually called peepso-messages and it’s language file msgso.pot
To avoid conflicts and having to redo all language files, we didn’t change the POT names.

Once you selected the POT file to translate, PoEdit will ask you what language you want to translate file to. Choose the language and press OK.

Now you are ready to start translating PeepSo to your language.
Enter your translations in a “Translation” box and do this for each string individually
Once you’re done with the translation, save the file. PoEdit will now ask you to name the translated file.

Translations must follow this naming convention:

pluginname-LANGUAGE_CODE.po

Note: The file must be saved using po extension. There is no typo here.

Examples:

If you wish to translate peepso-core.pot in German language, the file name will be peepso-core-de_DE.po
If you wish to translate friendso.pot in French language, the file name will be friendso-fr_FR.po
If you wish to translate picso.pot in Spanish language, the file name will be picso-es_ES.po

When you save the file, PoEdit will actually create two files, one with extension po and the other with extension mo

How to Discover What Language Code To Use

If you are not sure what language code you should be using when saving the file, you can use a very simple trick to learn what is the code you need.
Go to WP Admin -> Settings – General and change the language of your site.
Now take a look into ROOT/wp-content/languages
WordPress should already add some language files with appropriate language codes for selected language.

Applying translations

When you have all po and mo files ready, copy them into
ROOT/wp-content/languages/plugins/

Maintaining the Translation File

Because each new version of PeepSo and it’s supporting plugins contains a new .POT file, to remain accurate, translation files must be updated with each new release. To update the translation file:

Open your po translation file with PoEdit

Click “Catalog” and then “Update from POT File…

You will then see a summary of the updates including new strings that have been added and old strings that have will be removed.

Click “OK” to merge the changes into your translation file.
Translate the new strings.
Save the new po and mo files.

Userbar Widget in Your Theme

To add PeepSo UserBar widget anywhere in your template files, use WordPress function called the_widget

the_widget( 'PeepSoWidgetUserBar', "show_avatar=1&show_notifications=1&content_position=right" );

This specific code above render the widget with Avatar and Notifications, aligned to the right side.

Available options for this widget are:

  • guest_behavior= (hide / login) -Show/hide widget login link for guests
  • content_position= (left / right / center / space) -Align widget content
  • show_avatar=1 – Show user avatar
  • show_name=1 – Show user name
  • show_usermenu=1 – Show User Dropdown menu
  • show_notifications=1 – Show notifications
  • show_logout=1 – Show logout icon next to the notifications
  • show_vip=1 – Show VIP icons
  • show_badges=1 – Show Badges from BadgeOS integration

Every option has to be separated with “&”.

Here is the example with more options enabled:

the_widget( 'PeepSoWidgetUserBar', "guest_behavior=hide&show_avatar=1&show_notifications=1&show_name=1&content_position=left&logout=1" );