Social Link Technical Documentation

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.