Data sources - GavickPro/GK-News-Show-Pro GitHub Wiki

Data source is a model, which retrieves the data for the widget.

GK NSP have currently the following data sources:

• json
• rss
• wp
• wp_woocommerce
• xml

Every data source is placed in the own directory in the data_sources catalog. Data source should contain the following files:

• config-LANG.json - JSON file with configuration
• NAME.php - main data source file
• layout-parts.php - helper class with additional functions used for generating the article parts.

In example for json data source and the english language it will be:

• config-en_US.json
• json.php
• layout-parts.php

Below there is the JSON configuration file for the wp data source:

{
	"name": "wp",
	"data_source_types": [
		{
			"name": "wp-latest",
			"label": "Latest posts",
			"fields": [
					"offset",
					"orderby",
					"order"
				]
		},
		{
			"name": "wp-sticky",
			"label": "Sticky posts",
			"fields": [
					"offset",
					"orderby",
					"order"
				]
		},
		{
			"name": "wp-category",
			"label": "Categories slugs",
			"fields": [
					"data_source",
					"offset",
					"orderby",
					"order"
				]
		},
		{
			"name": "wp-tag",
			"label": "Tags",
			"fields": [
					"data_source",
					"offset",
					"orderby",
					"order"
				]
		},
		{
			"name": "wp-post",
			"label": "Posts slugs",
			"fields": [
					"data_source"
				]
		},
		{
			"name": "wp-custom",
			"label": "Custom post types",
			"fields": [
					"data_source"
				]
		}
	]
}

As you can see there are two main fields in the configuration object:

• name - it specifies the data source name and should be the same as the directory name
• data_sources_types - it is an array of available kind of queries for the specific data source. I.e. some data sources will use only one kind of query (like RSS, JSON, XML), when other will have more types of queries (like the mentioned example).

Every type of data source is defined with three fields:

• name - it must start with the following prefix DATA_SOURCE_NAME- i.e. "wp-"
• label - it is a text displayed on the data sources list
• fields - it is an array with additional fields displayed in the back-end when specific data source type iss elected. Currently there are available the following values:
  • data_source - textarea where user can put any data which will be useful for your query i.e. categories slugs separated by comma,
  • offset - value for the query, useful when you want to show i.e. posts in range <10,20>,
  • orderby - columns for ordering
  • order - type of order - ascending/descending

Some examples of the fields usage:

• data_source - user specifies the RSS feed url in the textarea,
• offset - useful when you are doing the queries using the WP_DB class
• orderby - currently it is limited to wordpress posts and woocommerce product queries.
• order - you can use it mainly when the orderby field is used.

Main file of the data source have the same name as the data source catalog. So the main file in the wp directory will be wp.php.

The main file should contain a class with at least two static methods. Every data source should provide two functionalities:

• returning data of items

• mapping the data to article formats values

• The class name should use the following syntax: class GK_NSP_Data_Source_NAME i.e. GK_NSP_Data_Source_wp

• There are required two static methods:

  • get_results($nsp, $amount_of_posts) - this method should return an array with results objects for every item.
  • get_article_format_mapping($item, $config) - this method should return an associative array where keys are the strings with their replacements as their values. Below there is an example of this kind of array:

return array(
			"{ID}" => $art_ID,
			"{URL}" => $art_URL,
			"{TITLE}" => $art_title,
			"{TEXT}" => $art_text,
			"{IMAGE_FULL}" => $art_image_full,
			"{IMAGE_LARGE}" => $art_image_large,
			"{IMAGE_MEDIUM}" => $art_image_medium,
			"{IMAGE_THUMBNAIL}" => $art_image_thumbnail,
			"{CATEGORIES}" => $art_categories,
			"{AUTHOR_ID}" => $art_author_ID,
			"{AUTHOR_NAME}" => $art_author_name,
			"{AUTHOR_URL}" => $art_author_URL,
			"{DATE}" => $art_date,
			"{COMMENT_COUNT}" => $art_comment_count,
			"{COMMENTS}" => $art_comment
		);

In every data source should be placed file layout-parts.php - this file contains the code responsible for generating the output (view). The class name should use the following syntax:

GK_NSP_Layout_Parts_NAME

i.e. GK_NSP_Layout_Parts_wp for the wp data source.

The class should contain the following methods:

• art_title($i, $only_value = false) - returns the article title with links, headers etc.
• art_text($i, $only_value = false) - returns the article text
• art_image($i, $only_value = false) - returns the article image
• art_info($i)- returns the article information block
• art_readmore($i, $only_value = false) - returns the article readmore button
• link_title($i) - returns the link title (used only in the default article wrapper)
• link_text($i) - returns the link text (used only in the default article wrapper)

All methods gets one important parameter - $i - the number of item in the results returned by the data source.

Additionally few methods have optional param $only_value. If it is set to true then the method returns raw data:

• art_title will return the article title
• art_text will return the article text
• art_readmore will return the article URL
• art_image will return the article image URL

Please remember to apply filters to the returned values.