bookmark_borderIncluding Scripts and Styles when using the Add-On Framework

Introduction

Scripts and styles can be included for an add-on by overriding the scripts() and styles() functions with structured arrays. All scripts and styles will be added automatically to the Gravity Forms no-conflict mode whitelist.

Scripts

The scripts() function must return an associative array with the following properties:

  • handle string

    The the script will be registered with WordPress using this handle

  • src string

    The URL of the script

  • version string

    The version number to be added to the query parameters for cache busting. Set to null to disable.

  • deps array

    An array of handles for scripts which are required before this script is loaded

  • in_footer boolean

    Determines if the scripts will be enqueued in the footer

  • callback array

    Function that is called when the script is enqueued

  • strings array

    An array of strings that can be accessed in JavaScript through the global variable [script handle]_strings

  • enqueue array

    An array of conditions for loading the script. See Enqueue Conditions.

IMPORTANT: When overriding this function, be sure to call parent::scripts() to ensure the base class scripts are enqueued.

Scripts Example

public function scripts() {
	$scripts = array(
		array(
			'handle'    => 'my_script_js',
			'src'       => $this->get_base_url() . '/js/my_script.js',
			'version'   => $this->_version,
			'deps'      => array( 'jquery' ),
			'in_footer' => false,
			'callback'  => array( $this, 'localize_scripts' ),
			'strings'   => array(
				'first'  => __( 'First Choice', 'simpleaddon' ),
				'second' => __( 'Second Choice', 'simpleaddon' ),
				'third'  => __( 'Third Choice', 'simpleaddon' )
			),
			'enqueue'   => array(
				array(
					'admin_page' => array( 'form_settings' ),
					'tab'        => 'simpleaddon'
				)
			)
		),
	);

	return array_merge( parent::scripts(), $scripts );
}

Styles

The styles() function must return an associative array with the following properties:

  • handle string

    The css file will be registered with WordPress using this handle

  • src string

    The URL of the css file

  • version string

    The version number to be added to the query parameters for cache busting. Set to null to disable.

  • deps array

    An array of handles for scripts which are required before this script is loaded

  • media string

    The media for which this stylesheet has been defined.

  • enqueue array

    An array of conditions for loading the css file. See Enqueue Conditions.

IMPORTANT: When overriding this function, be sure to call parent::styles() to ensure the base class scripts are enqueued.

Styles Example

public function styles() {
	$styles = array(
		array(
			'handle'  => 'my_styles_css',
			'src'     => $this->get_base_url() . '/css/my_styles.css',
			'version' => $this->_version,
			'enqueue' => array(
				array( 'field_types' => array( 'poll' ) )
			)
		)
	);

	return array_merge( parent::styles(), $styles );
}

Enqueue Conditions

Scripts and styles should always be loaded only when needed. The Add-on Framework provides a simple way to configure this for each of the JavaScript and CSS files. When overriding scripts() and styles() be sure to include the “enqueue” array with any or all of the following properties:

  • callback array

    Function that is called to determine if the script or stylesheet can be enqueued

    Example:

    array( $this, 'requires_script' )

  • admin_page array

    Specify one or more pages (known pages) where the script is supposed to be enqueued. When this setting is specified, scripts will only be enqueued in those pages. Possible values: form_editor, form_settings, plugin_settings, plugin_page, entry_view, entry_detail, results

    Example:

    array( 'admin_page' => array( 'form_settings', 'plugin_settings' ) )

  • tab array

    Specifies a form settings or plugin settings tab in which the script is supposed to be enqueued. If none is specified, the script will be enqueued in all of the form settings or plugin_settings pages

    Example:

    array( 'tab' => 'signature' )

  • query string

    Specifies a set of query string ($_GET) values. If all specified query string values match the current requested page, the script will be enqueued. Note that _empty_ and _notempty_ can be used as “smart” values

    Example:

    array( 'query' => 'page=gf_edit_forms&view=settings&id=_notempty_' )

  • post string

    Specifies a set of post ($_POST) values. If all specified posted values match the current request, the script will be enqueued

    Example:

    array( 'post' => 'posted_field=val' )

  • field_types array

    Specifies one or more field types that requires this script. The script will only be enqueued if the current form has a field of any of the specified field types. Only applies when a current form is available.

    Example:

    array( 'field_types' => array( 'signature' ) )