Article wrappers - GavickPro/GK-News-Show-Pro GitHub Wiki

Article wrapper is a container displayed around the articles. It is responsible for the widget design and behaviours.

You can select the article wrapper on the Widget layout tab:

Article wrapper selector

All article wrappers are located in the article_wrappers directory. Every article wrapper contains the following elements:

  • config-LANG.json - file with the article wrapper configuration
  • NAME.php - main file, the NAME must be the same as the directory name
  • helper.php - file with helper functions used by the article wrapper
  • NAME.css - (optional) file with CSS styles connected with the article wrapper output
  • NAME.js - (optional) file with the JS code for the specific article wrapper.

Of course you can create more php files if you need. But the mentioned files will be automatically loaded by the widget.

Config file

The configuration file contains the useful informations about each article wrapper. The data from the config files are cached and are loaded only in the back-end. Below there is an example config file for the news_gallery article wrapper:

{
	"name": "news_gallery",
	"tab_name": "News Gallery options",
	"css": true,
	"js": true,
	"support": [
		"wp",
		"wp_woocommerce",
		"json",
		"xml"
	],
	"params": [
		{
			"name": "pages",
			"label": "Number of pages",
			"tooltip": "Specify number of pages with news displayed in the widget",
			"classes": "short",
			"type": "text",
			"default": 3
		},
		{
			"name": "cols",
			"label": "Number of columns",
			"tooltip": "Specify number of columns with news displayed in the widget",
			"classes": "short",
			"type": "text",
			"default": 4
		},
		{
			"name": "autoanimation",
			"label": "Autoanimation",
			"tooltip": "Specify if the autoanimation will be used",
			"classes": "",
			"type": "switch",
			"default": 1
		},
		{
			"name": "animation_interval",
			"label": "Animation interval",
			"tooltip": "Specify the interval of autoanimation in miliseconds",
			"classes": "medium-right",
			"type": "text",
			"default": 5000,
			"after": "ms"
		}
	]
}

As you can see there are few main fields in the configuration file:

  • name - the name of the article wrapper displayed on the article wrappers list
  • tab_name - the name displayed on the tab with the article wrapper settings. If your article wrapper not needs own params set this field as false
  • css - (boolean) specifies if the CSS file will be loaded
  • js - (boolean) specifies if the JS file will be loaded
  • support - array with names of the supported by specific article wrapper data sources (if all data sources are supported set it as "all")
  • params - array of the parameters described below. If your article wrapper not need it - set it as false

Article wrapper parameters

Every custom parameter for the article wrapper should be defined with the following fields:

  • name - the name of option used in the storage
  • label - the text displayed before the option field
  • tooltip - tooltip for the label
  • classes - optional CSS classes (check the nsp-admin-css.css file for the available classes)
  • type - the type of the input element. Available types:
    • text - input text field
    • select - dropdown list
    • switch - dropdown list with predefined options On and Off
  • default - the default value of your field
  • after - optional text displayed after the field.

Additionaly for the options of the select type you can define options as the items object:

{
	"option_value": "option_name"
}

The tab with the article wrapper settings will appear after selecting specific article wrapper:

Article wrapper settings

Main file

The main file have rhes ame name as the article wrapper directory and can generate the article wrapper output. There is no special limits for the code. Please remember few useful facts:

  • the $this operator stores the handler to the main widget object, you can get easily an access to the widget configuration object through $this->config
  • you can get the custom article wrapper options using the following code:
$NAME_OPTION = $json_cache['NAME']->params[NUM]->default;

if(isset($this->config['NAME_OPTION'])) {
	$NAME_OPTION = $this->config['NAME_OPTION'];
}

Where:

  • NAME - is a article wrapper name i.e. news_gallery
  • OPTION - is a custom option name i.e. animation_interval
  • NUM - is an index of the option in the params array (indexed from 0)

It is worth to store the option values for the JS script as a data-* attributes of the main article wrapper container.

  • the data source results are stored in the $results array

helper file

The helper file contains the class with the name using following syntax:

GK_NSP_Article_Wrapper_NAME

i.e.

GK_NSP_Article_Wrapper_news_gallery

This class must contains at least one static method:

static function number_of_articles($config)

This method returns an information for the data source how many items should be retrived from the database.

CSS file

For easier styling we recommend to use in the articlew rapper main container some specific and unique CSS class whichi will be used as a prefix for all selectors.

JS file

The unique wrapper CSS class will be also useful for the JS scripts used in the article wrapper. Additionaly the data-* attributes in the main wrapper will make easier getting the instance dynamic parameters.