Each integrations consists of a config file, view folder and layout file.
The view folder is located in resources/views/domains/{integration_name}. The config file is located at config/domains/{integration_name}, where the integration_name is the website domain of the integration. In the view folder name all dots (.) from the domain name are replaced with underscore (_). For example if we have an integration with name “myproduct.newspaper.com” the view folder path will be resources/views/domains/myproduct_newspaper_com and the config file will be myproduct.newspaper.com.php
The layout file contains the header/footer and all of the client’s css and js files (fonts, dynamic header scripts, etc). The layouts are located in resources/views/layouts/domains/myproduct_newspaper_com.blade.php
Inside the view folder for each integration we have 4 main files for each diffrent page type we support plus a folder with dynamic scripts:
resources/views/domains/myproduct_newspaper_com/jsresources/views/domains/myproduct_newspaper_com/cssFor module system we use livewire. Check the docs here and here
In the livewire folder we put all of the scripts which are responsible for rendering the dynamic content for the integration (lastest articles, magazine articles, categories, navigations, paginations, prev/next buttons, related articles, etc.)
Those files are regular blade files therefore they must end with .blade.php extension.
All of these files are included/imported/called from the 4 main files we have or from each other. For example a file livewire/articles-list.blade.php may include livewire/categories-navigation.blade.php at the top to render a categories navigation module.
For example if we want to render an articles list in the homepage of the integration we can create a livewire/article-list.blade.php file. And include it in resources/views/domains/myproduct_newspaper_com/home.blade.php with the following snippet:
@livewire('front.articles', ['view' => 'articles-list', 'params' => [
'limit' => 10
]])
This will tell livewire to load Front\Articles component and pass it’s data to the articles-list.blade.php view file. Now inside this view file we gonna have a list of 10 articles (we specified the limit in the params section) . For full list of available params and diffrent front-end Components check the next section. Now inside the articles-list view file we can do a foreach loop over the $articles variable and render the markup we want.
We can also include categories view inside our home.blade.php file. Lets say we have a livewire/categories-navigation.blade.php
@livewire('front.categories', ['view' => 'categories-navigation'])
This will call the Front\Categories component and pass it’s data to the livewire/categories-navigation.blade.php view file. Now we have a $data variable inside that view which holds all the categories for this integration
The front end View Utilies are setting these variable accross all view files inside an integration. Full list:
array:21 [▼
"view" => ""
"category_id" => 0
"magazine_id" => 0
"article_id" => 0
"ad_id" => 0
"css_file" => "TRM106a6c241b8797f52e1e77317b96a201.css?ver=28b6dc7d573501f9aa6f18aa794b5585"
"js_file" => "TRM106a6c241b8797f52e1e77317b96a201.js?ver=28b6dc7d573501f9aa6f18aa794b5585"
"page_image" => ""
"page_type" => "home"
"page_num" => 1
"newspaper" => array:3 [▶]
"product" => array:7 [▶]
"category" => array:4 [▶]
"magazine" => array:3 [▶]
"device_type" => 1
"static_files_url" => "http://antoan.dev2.transmatico.com/storage/assets/extra.svz.de/"
"alias" => false
"static_cache_files_url" => "http://antoan.dev2.transmatico.com/storage/cache/extra.svz.de/"
"url" => "http://extra.svz.de:8076"
"full_url" => "http://extra.svz.de:8076"
"url_clean" => "http://extra.svz.de:8076"
]
This array with data will be passed as view parameter to every view in the integration, which means that these array elements will be available as variables inside the view files. For example ‘page_num’ element is availabe as $page_num variable inside the view and so on.
The variables will be available accross all the integration views and content will vary accordingly: for example the $categroy array will be empty on the home page or in the magazine page, since these are none-category specific pages. The $magazine array will be empty on category or home page etc.
File is called when the domain url is opened. Use to include the latest articles list, categories, etc.
Some of the more important variables:
| Name | Type | Description |
|---|---|---|
| $product | Array | Holds data for the product (id, name, etc) |
| $category | Array | Category data, usually all fields are empty/null on this page |
| $magazine | Array | Magazine data, usually all fields are empty null on this page |
| $newspaper | Array | Newspaper data |
| $device_type | Integer | 1 for desktop, 2 for mobile |
File is called when an article url is opened. Renders the article page in the specified way. The view file hold the data for the opened article (name, magazine, title, descript, etc.) Data available inside $article array:
"id" => 1875
"magazine_id" => null
"page" => 1
"name" => "Die Immobilie vor Schimmel schützen"
"alias" => "die-immobilie-vor-schimmel-schutzen-1875"
"headings" => "article headings|each heading separated with|"
"description" => "article description string"
"hubpage_image_id" => 112460
"meta_title" => "Die Immobilie vor Schimmel schützen"
"meta_description" => "meta description, if available place in the description section"
"meta_keywords" => null
"robots" => 0
"calculation_type" => 1
"ads_list" => null
"ads_count" => 0
"ads_mm_sum" => 313
"publishing" => "2022-01-26"
"start_date" => "2022-01-26"
"end_date" => null
"widget_end_date" => null
"ads_end_date" => null
"supervisor_id" => 0
"agent_id" => 13
"lang_type" => 2
"status" => 4
"active" => 1
"created_at" => "2022-01-25 15:45:23"
"updated_at" => "2022-02-09 09:11:56"
"deleted_at" => null
"primary_newspaper_id" => 131 // The id of the newspaper this articles belongs to
"primary_product_id" => 378 // The id of the product this articles belongs to
"legacy_id" => null
"heading1" => "Die Immobilie vor Schimmel schützen"
"heading2" => "dsadasdasdasdas"
"printHeaderImage" => "https://via.placeholder.com/968x105/f4f5f4/3c64a2?text=printheader"
"mainImage" => "http://main-img-url/GxC1zSXRI92FzmMT0WFUGXratp835HNf.png"
"mainImageCaption" => "A caption for the above image.",
"html" => "markup for the article from the article editor"
Use the above array data to build the article page.
Some of the more important variables:
| Name | Type | Description |
|---|---|---|
| $product | Array | Holds data for the product (id, name, etc) |
| $category | Array | Category data for the article category (depends on the category alias in the url) |
| $magazine | Array | Magazine data for the article magazine |
| $newspaper | Array | Newspaper data |
| $device_type | Integer | 1 for desktop, 2 for mobile |
| $article | Array | The data available for the opened article (check the code snippet above) |
File is called when category url is opened. Render the category pages. View file holds the data for the category (name, id, alias, etc). Use to render category articles with some livewire include. For example:
Some of the more important variables:
| Name | Type | Description |
|---|---|---|
| $product | Array | Holds data for the product (id, name, etc) |
| $category | Array | Category data, Check the code snippet below |
| $magazine | Array | Magazine data, usually all fields are empty null on this page |
| $newspaper | Array | Newspaper data |
| $device_type | Integer | 1 for desktop, 2 for mobile |
Data available inside $category array:
"name" => "Category name"
"alias" => "category-alias"
"icon_id" => null
"image_id" => null
"url" => "http://myintegration.newspaper.com/category-full-url"
Example articles include:
@livewire('front.articles', ['view' => 'articles-list', 'params' => [
'limit' => 10,
'specific_category' => true
]])
File is called when magazine url is opened. Renders the magazine page. View file holds the data for the opened magazine (name, id, alias, etc).
Some of the more important variables:
| Name | Type | Description |
|---|---|---|
| $product | Array | Holds data for the product (id, name, etc) |
| $category | Array | Category data, all empty fields on this page |
| $magazine | Array | Magazine data, check the code snippet below |
| $newspaper | Array | Newspaper data |
| $device_type | Integer | 1 for desktop, 2 for mobile |
Data available inside the $magazine array
array:4 [▼
"name" => "Wir feiern die Zwei – 2.2.2022"
"alias" => "wir-feiern-die-zwei-2-2-2022-februar"
"hubpage_image_id" => 123802
"url" => "http://extra.svz.de:8076/wir-feiern-die-zwei-2-2-2022-februar"
]
To include some magazine articles:
@livewire('front.articles', ['view' => 'articles-list', 'params' => [
'limit' => 10,
'specific_magazine' => true
]])
Location: app/Http/Livewire/Front/Articles.php
Get a list of articles by specificed params
Supported params:
public $DefaultParams = [
"specific_category" => false,
"categories" => [],
"random" => false,
"limit" => 10,
"specific_magazine" => false,
"magazines" => [],
"groupMagazines" => false,
"onlyMagazines" => false,
"pagination" => false,
"lastXDays" => 365*5,
"orderBy" => 'articles.publishing DESC, articles.id DESC',
"excludeIds" => [],
];
Data returned by the component
| Name | Type | Description |
|---|---|---|
| $data | Eloquent Collection | Collection of article models |
This front component returns a collection of articles. Each article is instance of App\Models\Article and the collection is Eloquent Collection , so we can use all of the available Laravel collection methods!
In addition to the $data variable, the component view will have all of the page specific variables provided (category.blade.php or magazine.page.blade etc.) depending on which page you included the component
When is param is passed the component is gonna try to read the current category from the ViewHelper and select articles only for this category
Specify array of category ids. The component is gonna try to fetch articles only for those categories
The limit of the articles to be fetched
Same as specific_category except for magazines
If provided this will group the articles by their magazine,so you will get only 1 article for each of the latest magazines. This is used when we’d like to show only a magazine overlay with counter and not to list multiple articles which belongs to a single magazine.
If param provided the component is going to fetch only articles which are assigned to magazines
Time limit for the articles
the ordering of the articles
The article ids which should not be fetched
If you need to display magazine’s articles on a category page or other hubpage (without actually being on the magazine page) you should pass this paramter to the component’s call. This param will eager-load all of the article’s magazine articles. After this they will be available under the magazine’s onlineArticles property.
$article->magazine->onlineArticles
It’s absolutely mandatory to use this param if you need to display magazine articles outside the magazine hubpage, otherwise they will be lazy loaded and this will heavily decrease performance/loading-times.
If you need to pass data from the parent view to the view rendered by the component call the blade_params parameter is used. It’s an array containing all of the variables you need to pass to the components view. The main purpose of this parameter is to make it easier to write/reuse multipurpose view components. Lets say you want to create a view with list of articles which supports pagination but the pagination should not be rendered everytime, we can call an Articles Component like this:
@livewire('front.articles', ['view' => 'related-articles-and-pagination', 'params' => [
'specific_category' => true,
'categories' => [1,2,3],
'blade_params' => [
'show_pagination' => true
]
]])
And inside our related-articles-and-pagination.blade.php we can do:
...some code goes here...
@if (isset($blade_params) && isset($blade_params['show_pagination']) && $blade_params['show_pagination'] == true)
...my pagination code hoes here...
@endif
Component is used to fetch the categories for the current product/integrations
The component will return $data array variable which will contain all of the categories.
Data returned by the component
| Name | Type | Description |
|---|---|---|
| $data | Array | Contains all of the integrations categories (active or otherwise specified). Each element reprents a category and each element is array (Check code snipper bellow) |
// Categories array data format
array:7 [▼
0 => array:15 [▼
"id" => 1143
"newspaper_id" => 18
"name" => "Lokales"
"alias" => "lokales"
"icon_id" => null
"image_id" => null
"on_hubpage" => 1
"order" => 0
"created_at" => "2022-06-14 13:37:59"
"updated_at" => "2022-06-14 13:37:59"
"is_active" => 1
"factor" => 1
"fa_icon" => null
"type" => 0
"url" => "http://extra.svz.de:8076/lokales"
]
1 => array:15 [▶]
2 => array:15 [▶]
3 => array:15 [▶]
4 => array:15 [▶]
5 => array:15 [▶]
6 => array:15 [▶]
]
Supported params:
public $DefaultParams = [
"specific_category" => false,
"categories" => [],
'category_type' => false,
'on_hubpage' => null
];
If set to true it will try to read the current category from the ViewHelper script and return data only for it.
List of category ids we want data for
Check App\Models\Category to see all category types. Currently we have regular category [type=0] and region category [type=1]
Pass this parameter is you want to speficy whether the fetched categories should have on_hubpage=1 or on_hubpage=0
This component is used to fetch the next and previous articles for the currently opened articles. It will return an array with 2 elements, the first being the previous article and the second will be the next article. The elements will be Eloquent Models.
Data provided from the component
| Name | Type | Description |
|---|---|---|
| $data | Array | Holds 2 elements. First is the previous article (null of not available), Second will be the next article (null if not available) |
The first/second elements (if available) will be an instance of App\Models\Articles, otherwise they will be null.
Require. Pass the currently opened article id as value of this parameter.
Required. Pass the publishing date of the currently opened article as value of this parameter.
When is param is passed the component is gonna try to read the current category from the ViewHelper and select articles only for this category
Specify array of category ids. The component is gonna try to fetch articles only for those categories
Same as specific_category except for magazines
Array of magazine ids
Example call:
@livewire('front.articles-navigation', ['view' => 'prev-next-navigation', 'params' => [
'specific_category' => $article['magazine_id'] && !$fake_magazine ? false : true,
'categories' => $article['magazine_id'] && !$fake_magazine ? [$category_id] : false,
'specific_magazine' => $article['magazine_id'] && !$fake_magazine ? true : false,
'magazines' => $article['magazine_id'] && !$fake_magazine ? [$article['magazine_id']] : [],
'current_article_id' => $article['id'],
'publishing' => $article['publishing']
]])
All of the integration layouts are based on blade template engine. Every meta tag has either a section or a variable as content attribute, so you can set it depenging on the page the user is currently opened.
The titles are not provided via sections from the view files, but as variable on system level. This means that you should not put @section('title') // code here @endsection blocks. Currently the titles are being build using the Product Label/Publisher Name fields in the product form in the UI. These fields are used in app/Helpers/ViewHelper@getTitle() method to build the correct title formats (according the page type we’re currently in).
The getTitle() functionality is then called from app/Http/Controllers/FrontEndController.php class in the run() method.
ViewHelper::addViewParam('title', ViewHelper::getTitle());
The only thing we need to do is make sure that in the layout we have a title meta tags which are printing our title variable. (In form of $title variable or @yield(’title’). The Blade engine will take care of rest)
<title>@yield('title')</title>
<meta property="og:title" content="@yield('title')" />
Meta description is set per page via section on integration level. For example on the article.blade.php page at the begining of the file we do:
@section('description')
@if (isset($article['meta_description']) && null != $article['meta_description'])
{{$article['meta_description']}}
@elseif (isset($article['description']))
{{$article['description']}}
@endif
@endsection
Make sure we have the corrent @yield expressions inside the integration layout:
<meta name="description" content="@yield('description')" />
<meta property="og:description" content="@yield('description')" />
Robots meta tags is set per page via section on integration level. For example on the article.blade.php page at the begining of the file we do:
@section('robots')
@if (isset($article) && isset($article['primary_product_id']) && $article['primary_product_id'] != $product['id'])
{{config('options.robots')[$product['robots']]}}
@elseif(isset($article) && isset($article['robots']))
{{config('options.robots')[$article['robots']]}}
@else
index,follow
@endif
@endsection
Make sure we have the corrent @yield expressions inside the integration layout:
<meta name="robots" content="@yield('robots')" />
Keywords meta tags is set per page via section on integration level. For example on the article.blade.php page at the begining of the file we do:
@section('keywords')
{{$article['meta_keywords']}}
@endsection
Make sure we have the corrent @yield expressions inside the integration layout:
<meta name="Keywords" content="@yield('keywords')" />
The following stack groups are available inside all integrations layout:
Before head tag:
@stack('top_css')<head>
Before the closing of head tag
@stack('head') @stack('css') @stack('bottom_css')</head>
Before the closing of body tag:
@stack('top_js') @stack('js') @stack('bottom_js')</body>