The site.php File | SP Page Builder (Pro) - Documentation | JoomShaper

SP Page Builder (Pro)

Updated Last: 19 April 2024

The site.php File

Once our fields are ready, we need to add code to visualize our addon. And we're going to do that inside the site.php.

The site.php file is responsible for rendering your addon contents to the site and the frontend editor.

Basic Addon Rendering Syntax

You have to declare a class SppagebuilderAddonYourAddonName which should extend the base class SppagebuilderAddons.

class SppagebuilderAddonYourAddonName extends SppagebuilderAddons
{
	/**
     * Render the Addon
     *
     * This method is responsible for rendering the HTML structure of the addon based on its settings.
     *
     * @return string The HTML string representing the addon's output.
     */
	public function render()
	{
		// Retrieve addon settings
		$settings = $this->addon->settings;
		$output = '';

		// Generate the HTML structure of the addon and store it in the $output variable

		return $output;
	}
    /**
     * Generate CSS Styles
     *
     * This method generates the CSS styles for the addon based on its settings and returns the CSS string.
     *
     * @return string The CSS string representing the addon's styles.
     */
	public function css()
	{
		// Retrieve addon settings
		$settings = $this->addon->settings;
		$addon_id = '#sppb-addon-' . $this->addon->id;
		$cssHelper = new CSSHelper($addon_id);

		$css = '';

		$css .= $cssHelper->generateStyle(
			'.your-css-selector',
			$settings,
			[
				'setting_key' => 'a_valid_css_property_associate_with_the_setting',
				'another_key' => ['property_1', 'property_1']
			],
			[
				'setting_key' => '%',
				'another_key' => false
			]
		);

		// Generate your other CSS here...

		return $css;
	}
    /**
     * Inline JavaScript
     *
     * This method allows you to add any inline JavaScript code specific to the addon.
     *
     * @return string The inline JavaScript code.
     */
	public function js()
	{
		$script = '';

		// Return any inline script if you need.
		return $script;
	}
    /**
     * External Stylesheets
     *
     * This method returns an array of external stylesheets to include for the addon.
     *
     * @return array An array of stylesheet paths.
     */
	public function stylesheets()
	{
		return [
			'path/to/your/stylesheet.css',
			'path/to/your/another/stylesheet.css',
		];
	}
    /**
     * External Scripts
     *
     * This method returns an array of external scripts to include for the addon.
     *
     * @return array An array of script paths.
     */
	public function scripts()
	{
		return [
			'path/to/your/script.js',
			'path/to/your/another-script.js',
		];
	}
    /**
     * Get Frontend Editor Template
     *
     * This method generates the lodash template string that will be used in the frontend editor for the addon.
     *
     * @return string The lodash template string.
     */
	public function getTemplate()
	{
		$lodash = new Lodash('#sppb-addon-{{ data.id }}');
		$output = '';

		$output .= $lodash->alignment('css-property', '.selector', 'data.settings_key');
		$output .= $lodash->color('css-property', '.selector', 'data.settings_key');

		return $output;
	}
}

Please note that you have to follow this structure for your custom addon.
Here's the breakdown of the methods inside the SppagebuilderAddonYourAddonName class.

render()

Syntax

public function render()
{
}

Parameters

No parameter

Return Value

The addon's HTML string.

Description

The render method is responsible for rendering the HTML structure of the addon based on its settings. You can access the addon's settings using the $this->addon->settings variable.

css()

Syntax

public function css()
{
}

Parameters

No parameter

Return Value

The addon's CSS string.

Description

The CSS method generates the CSS styles for the addon based on its settings and returns the CSS string.

generateStyle()

Syntax

public function generateStyle(string $selector, $settings, $propMap, $unit = 'px', $modifier = [], $default = null, $important = false, $static = ''): string
{
}

Parameters

$selector

  • type => string
  • The CSS selector.

$settings

  • type => object
  • The full addon settings object from $this->addon->settings.

$propMap

  • type => associative array
  • An associative array that maps the settings keys to the CSS-properties.
  • Example:
$propMap = [
	'some_color_key' => 'color',
	'some_width_key' => ['max-width', 'flex-basis']
];
  • Here, the value of the $settings->some_color_key will be applied to the color property and the output would be color: #the_color_value;
  • You could apply the same setting's value to multiple CSS properties.
  • For example here the value of the $settings->some_with_key will be applied to the max-width and  flex-basis properties and the output would be max-width: 100px; flex-basis: 100px;. Here, the 100px is just an example.

$unit (optional)

  • type => string | array
  • The $unit parameter in the generateStyle() method allows you to specify the unit for your setting values. It can be either a string or an array.
  • If you pass a string as the $unit parameter, that unit will be applied to all the properties mentioned in the $propMap. For example, if you pass px, all the values in the generated CSS will have the unit px.
  • If you want to specify a different unit for each key declared in the $propMap, you can pass an array as the $unit parameter. In this case, the array should be an associative array where the keys correspond to the keys in $propMap and the values represent the units for each specific key.
  • Example:
$unit = [
	'some_color_key' => false, // No unit needed for color
	'some_width_key' => '%' // Use percentage unit for max-width and flex-basis
];
  • Here for the color value we don't need to pass any unit, so we pass false.
  • For the width key we pass the percentage as a unit.

$modifier (optional)

  • type => array
  • Example
$modifier = [
	'some_padding_margin_key' => 'spacing'
];
  • Currently, the only supported modifier type is spacing. When you define a key in the $modifier array with the value spacing, it indicates that the corresponding value in $propMap represents spacing values that need to be converted into separate CSS properties.

For example: If the value of $settings->some_padding_margin_key is '10px 20px 10px 20px', the generateStyle() method will convert it into separate CSS properties as follows:

padding-top: 10px;
padding-right: 20px;
padding-bottom: 10px;
padding-left: 20px;

$default (optional)

  • type => any
  • Example
$default = [
	'some_key' => '100em'
];
  • The $default array specifies that, the value of $settings->some_key will be skipped and replaced with the default value 100em.

$important (optional)

  • type => boolean | array
  • Example
$important = [
	'some_key' => true
];
  • This will add an !important; suffix to the CSS property.

$static (optional)

  • type => string
  • Example
$static = 'box-sizing: border-box;';
  • If we want to add some static styles we could pass it, and the style will be concatenated with the generated style.

js()

Syntax

public function js()
{
}

Parameters

No parameter

Return Value

The addon's inline javascript string.

Description

The js method allows you to add any inline JavaScript code specific to the addon. Write your JavaScript code and return it as a string. This script will be added to the page.

stylesheets()

Syntax

public function stylesheets()
{
}

Parameters

No parameter

Return Value

An array of external stylesheets

Description

The stylesheets method returns an array of external stylesheets to include for the addon. Add the paths to your external stylesheets in this method.

scripts()

Syntax

public function scripts()
{
}

Parameters

No parameter

Return Value

An array of external scripts

Description

The scripts method returns an array of external scripts to include for the addon. Add the paths to your external scripts in this method.

getTemplate()

Syntax

public function getTemplate()
{
}

Parameters

No parameter

Return Value

The lodash template string

Description

The getTemplate method generates the lodash template string that will be used in the frontend editor for the addon.

If you skip this method, the frontend editor will request the content from the render() method and send an asynchronous request on every field change.