Addon Data Interface

Addon file name

The placeholder ADDON_NAME is coming from your addon's file name, with all dashes replaced by underscores and the .php extension removed.

Example: my-first-addon.php will be my_first_addon.

Mandatory functions

You must provide the following functions in your addon to make the plugin be able to interface with it.

Function: wpcz_addon_<ADDON_NAME>_version()

Description:
This function gives back your addon's version number to the plugin as a string.

Arguments:

void

Returns: string

Example code:

function wpcz_addon_my_first_addon_version() {
	return '1.0.0';
}

Function: wpcz_addon_<ADDON_NAME>_name()

Description:
This function gives back your addon's displayable name to the plugin as a string.

Arguments:

void

Returns: string

Example code:

function wpcz_addon_my_first_addon_name() {
	return 'My First Addon';
}

Function: wpcz_addon_<ADDON_NAME>_init()

Description:
This function does the initialization of your addon, called by the interfacing plugin at it's initialization.

Arguments:

void

Returns: void

Example code:

function wpcz_addon_my_first_addon_init() {
	global $the_plugin;
	
	if ( $the_plugin->is_client ) {
		/* Do frontend initialization. */
	} else {
		/* Do admin initialization. */
	}
	/* For component and layout functions, see the Addon Component Interface section. */
}

Optional functions

You can provide the following optional functions too, if you need them.

Addon post

Function: wpcz_addon_<ADDON_NAME>_post()

Description:
You can process the POST queries the admin surface sent to you addon via this function. The argument $data is a named array containing the fields of the request, sent to the backend.

Arguments:

$data | Type: array

Returns: array

The returning array contains the following fields:

failed: A bool which indicates if the operation was successful, or not.
errors: A named array containing the problematic field names from $data as keys and the error messages as values.

Example code:

function wpcz_addon_my_first_addon_post( $data ) {
	global $the_plugin, $wpdb;

	$failed = false;
	$errors = array();
	if ( !$the_plugin->is_userside ) {
		$fails = array( '', 'Field not set.', 'Field is empty.', 'Field contains unwanted string.' );
		if ( !isset( $data[ 'test_input_1' ] ) ) {
			$failed = true;
			$fail = 1;
		} else if ( empty( $data[ 'test_input_1' ] ) ) {
			$failed = true;
			$fail = 2;
		} else if ( is_int( strpos( $data[ 'teszt_input_1' ], 'unwanted string' ) ) ) {
			$failed = true;
			$fail = 3;
		}
		if ( !$failed ) {
			$wpdb->query( 'UPDATE `my_first_addon_table` SET `textval`=\'' . $data[ 'test_input_1' ] . '\' WHERE `name`=\'test_input_1\' LIMIT 1' );
		} else {
			$errors[ 'test_input_1' ] = $fails[ $fail ];
		}
	}
	return array( 'failed' => $failed, 'errors' => $errors );
}

Addon AJAX

Function: wpcz_addon_<ADDON_NAME>_ajax()

Description:
This function handles the AJAX GET requests, sent to your addon via the wpcztpfm.addonAjax() JS function of the plugin. The argument $data is a named array containing the fields of the request, sent to the backend.

Arguments:

$data | Type: array

Returns: array

The returning array can contain anything, it will become a JSON array on the public view, for further client side processing.

Example code:

function wpcz_addon_my_first_addon_ajax( $data ) {
	global $the_plugin;

	if ( $the_plugin->is_userside ) {
		$res = $the_plugin->getres( 'SELECT `anything` FROM `something` WHERE `something_else` LIKE \'%' . $data[ 'an_input' ] . '%\' LIMIT 1' );
		return array( 'answer' => $res[ 'anything' ] );
	} else {
		/* Do something else...or not. */
	}
}

Function: wpcztpfm.addonAjax()

Description:
This JS function of the plugin does the AJAX query for addons. You specify the addon's name in addonName and you can give further HTTP arguments in additionalURLParts and the POST query data in query if you want to do a POST query. Pass false for a GET query. callback will be called on success and errorCallback will be called on error. Pass false for them if they are not needed. rootElement is the selector for the preloader's element which will be visible during loading and hidden after. Pass false for it, if not needed.

Arguments:

addonName | Type: string
additionalURLParts | Type: string
callback | Type: function / bool
errorCallback | Type: function / bool
query | Type: string / bool
rootElement | Type: string / bool

Returns: void

Example code:

wpcztpfm.addonAjax(
	'my_first_addon',
	'&getSomething=whatever',
	function (result) {
		var response = JSON.parse(result);
		showResponse('info', response.answer);
	},
	function () {
		showResponse('error', 'Network error.');
	},
	false,
	false
);

wpcztpfm.addonAjax(
	'my_first_addon',
	'',
	function (result) {
		var response = JSON.parse(result);
		showResponse('info', response.answer);
	},
	function () {
		showResponse('error', 'Network error.');
	},
	'&postSomething=whatever',
	false
);

Addon import/export

All WPCoderz plugins can import and export their data tables, including the addons'. The addon data import/export has to be handled in the addon itself though. The WPCoderz dump contains two types of lines: command lines and data lines. There are several commands, but the addon has to deal with @addon_data solely.

Function: wpcz_addon_<ADDON_NAME>_import_init()

Description:
This function initializes the import procedure, e.g.: sets the used variables to default, etc. During an import, when the importer encounters the command of @addon_name=my_first_addon, this function of my_first_addon will be called and until a different addon name is specified, this addon will be feed with the command and data lines.

Arguments:

void

Returns: void

Example code:

$wpcz_addon_my_first_addon_importing_table = false;

function wpcz_addon_my_first_addon_import_init( ) {
	global $wpcz_addon_my_first_addon_importing_table;

	$wpcz_addon_my_first_addon_importing_table = 'my_first_addon_stuff';
}

Function: wpcz_addon_<ADDON_NAME>_import_data()

Description:
When the importer feeds the selected addon and encounters a command line with @addon_data, it will call this function of the addon and pass the given addon data to it, via the $data argument. This might be used to set the currently filled up table's name and perhaps to clear it...but the exact mechanism is left to the user, it is not really etched in stone.

Arguments:

$data | Type: string

Returns: void

Example code:

function wpcz_addon_my_first_addon_import_data( $data ) {
	global $wpcz_addon_my_first_addon_importing_table, $wpdb;

	$wpcz_addon_my_first_addon_importing_table = $data;
	$wpdb->query( 'TRUNCATE `' . $wpcz_addon_my_first_addon_importing_table . '`' );
}

Function: wpcz_addon_<ADDON_NAME>_import_line()

Description:
During the feeding of the addon import, this function is called at each data line, the exact line is passed to the function via the $line variable. This might be used to insert the table rows, but as with wpcz_addon_<ADDON_NAME>_import_data(), it is up to the user, what this function will do.

Arguments:

$line | Type: string

Returns: void

Example code:

function wpcz_addon_my_first_addon_import_line( $line ) {
	global $wpdb, $wpcz_addon_my_first_addon_importing_table;

	$wpdb->query( 'INSERT INTO `' . $wpcz_addon_my_first_addon_importing_table . '` VALUES (\'' . str_replace( "\t", "','", $line ) . '\')' );
}

Function: wpcz_addon_<ADDON_NAME>_export()

Description:
When the plugin's exporting mechanism is called, the plugin calls this function in all addons. The addon can then give back a string to the plugin with all it's data in it. It may also use the @addon_data command to set which table contains the following data lines.

Arguments:

void

Returns: string

Example code:

function wpcz_addon_my_first_addon_export() {
	global $teszt_project;

	$result = '@addon_data=my_first_addon_table' . "\n";
	$res = $teszt_project->getres( 'SELECT * FROM `my_first_addon_table`' );
	if ( !is_null( $res ) ) {
		foreach ( $res as $row ) {
			foreach ( $row as $field ) {
				$result .= str_replace( array( "\\", "\t", "\n", "\r" ), array( "\\\\", "\\t", "\\n", "\\r" ), $field ) . "\t";
			}
			$result[ strlen( $result ) - 1 ] =  "\n";
		}
	}
	return $result;
}