CloudArcade Plugin Development Guide

This page explains the key parts of plugin development for CloudArcade CMS.

Important Plugin Files:

• info.json (Required)
• admin-page.php (Required)
• admin-hook.php (Optional)
• public.php (Optional)
• header.php (Optional)
• footer.php (Optional)

info.json

The info.json file contains essential plugin information like the plugin name, description, version, and more.

Example:

{
	"name": "Query Cache",
	"version": "1.0.2",
	"author": "CloudArcade",
	"description": "Speed up your site by caching SQL query with Redis or Memcached.",
	"website": "https://cloudarcade.net",
	"documentation": "https://cloudarcade.net/plugins/query-cache-plugin/",
	"require_version": "1.8.7",
	"tested_version": "1.8.7",
	"initial_release": "16/04/2024",
	"last_update": "16/04/2024",
	"type": "plugin",
	"target": "index",
	"require_login": true
}

The target, require_login, and type keys are not currently used but should be filled based on your plugin’s functionality.

target: Can be "index" (for public pages) or "admin" (for admin pages). For example, if the target is "admin", the plugin is for admin functionality only, like the “Sitemap” plugin.

admin-page.php

The admin-page.php file is used to create the plugin’s admin page. This is where plugin configurations and interactions for admin users take place.

While some older plugins may still use page.php and it will continue to work, it’s recommended to use admin-page.php to follow the latest naming conventions.

admin-hook.php

Starting from CloudArcade v1.9.5, plugins can include an admin-hook.php file to extend admin panel functionality. This file is automatically loaded after essential admin code execution, allowing plugins to:

• Add custom admin interfaces
• Create new admin menu items
• Register new game types
• Add notifications to the admin dashboard
• Hook into various admin panel sections

Example code:

// plugins/your-plugin/admin-hook.php

add_admin_hook('admin_dashboard_notifications', function() {
    // Add notifications to admin dashboard
    show_alert('Your plugin needs attention!', 'warning');
});

// Register new game type
register_game_type('custom', 'Custom Game', 'custom-template');

Note: The admin-hook.php file will only be loaded when accessing the admin panel.

public.php

The public.php file runs on all visitor pages (front-end) and is the only way for your plugin to interact with the user-facing part of the site (theme).

Examples of plugins using public.php:

1. Adblock Detector: Inserts JavaScript to detect ad blockers and display an alert.
2. Contact Form: Adds a shortcode that can be executed on pages, and inserts JavaScript into the footer.
3. Cookie Consent: Inserts an HTML element for cookie consent.

You can use all functions from theme-functions.php within public.php. This file contains various useful functions for themes.

Older plugins use main.php instead of public.php. Both files work the same way, but it’s recommended to use public.php going forward.

header.php

If your plugin has a header.php file, it will be included in the theme’s header.php when the function load_plugin_headers() is called. All official themes call this function in their header.php.

footer.php

If your plugin has a footer.php file, it will be included in the theme’s footer.php when load_plugin_footers() is called. All official themes call this function in their footer.php.

Using CMS Functions in Your Plugin Code

Here are some key CMS functions you can use to enhance your plugin development. These functions are commonly used.

1. add_to_hook($hook_name, $callback)

Usage: public.php only

This function allows you to insert PHP code at a specific location in the theme.

Example:

add_to_hook('footer', function(){
	$custom_template = dirname(__FILE__) . '/template-custom.php';
	if (file_exists($custom_template)) {
		include($custom_template);
	} else {
		include(dirname(__FILE__) . '/template-default.php');
	}
	?>
	<script type="text/javascript" src="<?php echo DOMAIN ?>content/plugins/adblock-detector/ad-handler.js"></script>
	<?php
});

In the example above, the PHP code inserts a JavaScript file into the theme’s footer.

2. add_shortcode($tag, $callback)

Usage: public.php only

This function creates a shortcode, which can be executed within pages or theme code.

Example:

add_shortcode('hello-world', function() {
	return 'Hello World!';
});

To use the shortcode:

In PHP: <?php echo run_shortcode('[hello-world]'); ?>

In a page: [hello-world]

For additional functions, refer to content/themes/theme-functions.php. Note that only public.php can run functions from theme-functions.php.

3. set_plugin_pref($plugin_slug, $key, $value)

This function can be called on admin-page.php and public.php

This function is primarily used in admin-page.php to save plugin configuration changes made by the user.

set_plugin_pref('query-cache', 'active', true);

or

set_plugin_pref('sample-plugin-slug', 'value', 'sample value');

This saves the values to the database.

4. get_plugin_pref($plugin_slug, $key, $default = null)

This function can be called on admin-page.php and public.php

This function retrieves the saved plugin option or preference values, such as user settings.

get_plugin_pref('query-cache', 'active');

You can also set a default value if the preference does not exist in the database:

get_plugin_pref('query-cache', 'active', false);

5. get_plugin_pref_bool($plugin_slug, $key, $default = false)

This function differs from get_plugin_pref() as it only accepts the strings 'true' or 'false'.

It’s recommended to use this function for boolean values, though you can still use get_plugin_pref() for the same purpose if needed.

For plugin code examples, you can check the existing official plugin code or download the Sample Plugin below as a starter for your own plugin.

Download Sample Plugin