Social Link Technical Documentation

Installation

Basic Install

To install this plugin, you can copy the files into the plugins directory of your WordPress install. An easy way to do this is to clone the repository from GitHub:

$ cd my-site/wp-content/plugins
$ git clone https://github.com/IIP-Design/social-link-optimizer.git

Composer Install

If using a Composer build process, add a reference to the plugin’s git repository to the repositories array of your composer.json. In the require section, add an entry for gpalab/social-link-optimizer pointing to the version of the plugin you would like to use. Your resulting composer.json file will look something like this:

{
  "name": "sample-webroot",
  "repositories": [
    {
      "type": "git",
      "url": "git@github.com:IIP-Design/social-link-optimizer"
    },
    {
      "other repo": "..."
    }
  ],
  "require": {
    "gpalab/social-link-optimizer": "*",
    "other-dependency": "..."
  }
}

Activation

Once the plugin is installed, you can go to the installed plugins in the WordPress admin panel and click on the Activate link under the Social Link Optimizer plugin.

Activation of the plugin will add an entry for the plugin settings to the site’s options table. It will create the custom capabilities that will be used to manage the plugin (form more information see the section on permissions).

Uninstall

To deactivate the plugin go to the installed plugins in the WordPress admin panel and click on the Deactivate link under the Social Link Optimizer plugin.

To completely removed the plugin, first deactivate the plugin. Once deactivated, you should see the Deactivate link replaced with a Delete link. [Note that on a multisite installation, you can only delete a plugin from the network admin.]

Please note that deleting the plugin runs a series of uninstall hooks to clean up the database. These hooks will:

  1. Delete the plugin settings saved in the options table,
  2. Delete the custom capabilities created by the plugin to manage permissions,
  3. Delete the metadata saved to social link pages,
  4. Change the page template on all social link pages from Social Link Optimizer to Default, and
  5. Delete all added social links.

These deletions are irreversible so please only delete the plugin if you are certain that you no longer want to use this data and/or that you have backed up your database.

Development

Please note that ESLint and PHP Codesniffer will run on every commit to ensure that the plugin’s code is conforming to the correct standards. If any code fails this linting, you will not be able to complete your commit. As such it is highly recommended that you integrate ESLint and PHP Codesniffer into your preferred text editor or frequently run the linting script npm run lint.

To compile the plugin’s JavaScript files for production, run the command npm run build, which will update the production files in the admin/build directory.

Plugin Structure

This plugin contains a social-link-optimizer.php file, which registers the plugin and begins its execution. There is an admin directory (admin) where all functions relating to the admin portion of the plugin are registered and a public directory (public) where all functions relating to the plugin’s frontend are registered. The includes directory contains the main plugin class (include/class-slo.php) - which defines the core functionality of the plugin, the loader class (include/class-loader.php) - which feeds the admin and public hooks in from their respective classes into the main class file, and activator/uninstall hooks - which define the plugin’s behavior upon installation/deletion.

Below is a more detailed listing of key plugin files and directories:

root
├── social-link-optimizer.php # Entry point for the plugin.
│
├── admin # All files pertaining to the administrative portion of the plugin.
│   │
│   ├── class-admin.php # Registers (and localizes) admin scripts, styles, and post metadata.
│   ├── class-ajax.php # Handles AJAX calls needed to persist data on the server.
│   ├── class-archive.php # Configures the admin interface for the social links page template.
│   ├── class-cpt.php # Adds a custom post type that is used to add social link data.
│   ├── class-permissions.php # Adds and manages custom WordPress capabilities used by the plugin.
│   ├── class-settings.php # Adds a Social Links menu item to the administrative panel.
│   ├── class-ure.php # Integrates this plugin with the User Role Editor plugin.
│   ├── build # Production builds of admin JavaScript bundles (generated by running `npm run build`)
│   ├── css # Settings page CSS
│   └── js # (Un-transpiled) JavaScript for the plugin settings page and
│
├── includes # Registering and implements all classes.
│   │
│   ├── class-activator.php # Actions run on the plugin's activation.
│   ├── class-loader.php # Loader file, which runs all needed action and filter hooks.
│   ├── class-slo.php # Registers the SLO class and imports/instantiates all the plugin's classes.
│   └── class-uninstall.php # Actions run on the plugin's deletion.
│
├── public # All files pertaining to the frontend portion of the plugin.
│   │
│   ├── assets # Social icons used by the social links page template.
│   ├── class-frontend.php # Registers and localizes frontend scripts and styles.
│   ├── class-template.php # Adds a the social links page to the list of page template options.
│   └── css # The social links page template CSS.
│
├── templates # Template files for the social links page template.
│   │
│   ├── archive-gpalab-social-link.php # Renders the social links page template.
│   └── template-parts # Part used by the social links page template.
│
├── docs # Plugin documentation.
└── webpack.config.js # Customizes the configurations used by wp-scripts to build the production JS bundles.

Permissions

This plugin adds a number of custom WordPress capabilities that allow site admins to manage who has access to use/configure the functionality provided by the plugin. The capabilities consist of three core capabilities for configuring social link pages and a group capabilities relating to individual social links.

The three core capabilities are:

  1. gpalab_slo_manage_settings - Provides access to the plugin’s settings page.
  2. gpalab_slo_add_slo_page - Allows user to assign the Social Link Optimizer template to a page.
  3. gpalab_slo_edit_slo_page - Allows user to update the properties of a social link page.

By default, only users assigned the role Admin will have these core capabilities.

The plugin also adds a group of capabilities pertaining to the creation/editing of individual social links. These capabilities correspond to the set of capabilities used to manage posts/pages and provide the equivalent permission (excluding those for private posts). They are:

  • gpalab_slo_edit_links
  • gpalab_slo_edit_others_links
  • gpalab_slo_edit_published_links
  • gpalab_slo_delete_links
  • gpalab_slo_delete_others_links
  • gpalab_slo_delete_published_links
  • gpalab_slo_publish_links

By default, users with the role Editor and higher have access to these capabilities.

These custom capabilities can easily be integrated into any WordPress role/user management tool. In fact this plugin integrates with the User Role Editor plugin out of the box.