README

Display configured socialwall contents.

This module allows to display contents as:

• Live Wall
  Setting a tag/keyword, this module will display contents automatically fetched from configured social networks with the desired tag/keyword.
  To avoid api massive requests consumptions, the contents are cached.
  To download new contents and rebuild automatically socialwalls, you need to run a couple of commands explained below to fetch new data automatically.
  Contents in a live wall may be removed automatically if removed from a social network or if too old because there is a limit of social posts fetched due to api limits.
  If you don't want to have a live wall posts list rebuild, you can uncheck the "automatically rebuild socialwall" flag in the form widget.
• Picked posts wall
  Allows to select and store data from social networks inside the app and also allows to edit contents (posts) to be displayed in socialwalls.
  The stored posts will be available and editable until will be manually removed from inside this app.

At the moment, Instagram posts will ALWAYS be fetched from the app database inside the Instagram stored contents table (due to the extremely restricted api calls available for developer unpublished instagram apps). Facebook and Twitter posts will ALWAYS be fetched using the API calls.

Functions to fetch live data from Instagram are also available.

At the moment, Twitter apis allows to fetch the last 7 days posts.

At the moment, the supported social networks for this plugin are:

• Facebook - it is MANDATORY to create a BUSINESS app that allows to use the Facebook Login for Business
• Instagram
• Twitter

At the moment, for Facebook and Instagram, a user with SOCIALWALL_ADMIN permission needs to manual update the tokens for retrieving contents for social networks. The token expiration dates will be shown in the socialwall tokens crud available in the module (see more infos below).

Will try to renew tokens automatically, if allowed, as soon as possible. See relative section below.

Installation

You need to require this package and enable the module in your configuration.

add to composer requirements in composer.json

"open20/social-wall": "dev-master",

or run command bash:

composer require "open20/social-wall:dev-master"

Enable the Socialwall module in the modules.php file of the desired backend/frontend/common (recommended) folder, adding:

 'socialwall' => [
        'class' => 'open20\socialwall\Module', # ALWAYS REQUIRED
        'modulesIdClassMapEnable' => [
            'elitedivision\amos\news\models\News' => 'news',
        ],
        'enableAdvancedSocialConfigs' => false,
        'rteToolbar' => "styleselect | bold italic strikethrough | link unlink image | alignleft aligncenter | numlist bullist outdent indent | removeformat",
 ],

all the params added in the example above will be explained below

add socialwall migrations to console modules (console/config/migrations-amos.php):

'@vendor/open20/social-wall/src/migrations'

in the params.php or params-local.php file, you need to set some data and the relative social app configuration data provided by each social network:
e.g.

    'instagram' => [
        'client_token' => '<CLIENT TOKEN HERE>',
        'client_id' => '<CLIENT ID HERE>',
        'client_secret' => '<CLIENT SECRET HERE>',
        'redirect_uri' => '<YOUR APP URL>/socialwall/socialwall-tokens/instagram-account-handler', # NEEDS TO BE SET IN THE INSTAGRAM DEVELOPER PANEL WHEN ASKING FOR APP TOKENS
        'last_days_posts' => 30, # CURRENTLY UNUSED FOR INSTAGRAM
        'profile_pictures_url' => [ # LIST OF DESIRED PROFILE IMAGE URLs FOR EACH ACCOUNT ID, see more info below
            "<IG ACCOUNT ID>" => '<URL OF PROFILE IMAGE>',
            "<IG ACCOUNT ID>" => '<URL OF PROFILE IMAGE>',
        ],
        'apiVersion' => 'v17.0', # OPTIONAL, CAN SELECT MANUALLY API VERSION ENABLED FOR INSTAGRAM APP TOKEN
    ],
    'twitter' => [
        "max_results" => 30
    ],
    'facebook' => [
        'client_id' => '<CLIENT ID HERE>',
        'client_secret' => '<CLIENT SECRET HERE>',
        'client_token' => '<CLIENT TOKEN HERE>',
        'js_sdk_token' => '', # CURRENTLY UNUSED
        'redirect_uri' => '<YOUR APP URL>/socialwall/socialwall-tokens/facebook-accounts-selection', # NEEDS TO BE SET IN THE FACEBOOK DEVELOPER PANEL WHEN ASKING FOR APP TOKENS
        'last_days_posts' => 30, # CURRENTLY UNUSED FOR FACEBOOK
        'apiVersion' => 'v17.0', # OPTIONAL, CAN SELECT MANUALLY API VERSION ENABLED FOR FACEBOOK APP TOKEN
    ],

Configurable fields - Module parameters

This is the list of the configurable fields for the Socialwall module with the default parameters used if a different value is not set.

• rteToolbar - string, default: bold italic strikethrough | removeformat
  Toolbar settings for the TextEditorWidget in the socialwall (picked) posts form
• modulesIdClassMapEnable - array, default: not set
  List of enabled models where the socialwall widgets will be shown.
  Keys are the classes enabled, values are the module mapping ids used in the database for storing data.
  Different models may have the same module mapping.
  Please note that only including a model in the list will not assure that the socialwall widgets will be shown (the socialwall widgets need to be integrated and available inside the desired modules).
  e.g.

        'modulesIdClassMapEnable' => [
            'elitedivision\amos\news\models\News' => 'news',
        ],
  

• enableAdvancedSocialConfigs - boolean, default: false
  Flag to enable or disable the advanced fields in the socialwall tokens cruds (for example for using manual facebook or instagram tokens inside the application).
• enabledSocials - array, default: see example below
  List of social networks enabled
  e.g.

        'enabledSocials' => [
            open20\socialwall\utility\Social::FACEBOOK => open20\socialwall\utility\Social::SOCIAL_LABELS[open20\socialwall\utility\Social::FACEBOOK],
            open20\socialwall\utility\Social::INSTAGRAM => open20\socialwall\utility\Social::SOCIAL_LABELS[open20\socialwall\utility\Social::INSTAGRAM],
            open20\socialwall\utility\Social::TWITTER => open20\socialwall\utility\Social::SOCIAL_LABELS[open20\socialwall\utility\Social::TWITTER],
        ],
  

• enabledSocialwallTypes - array, default: see example below
  List of socialwall types available
  e.g.

        'enabledSocialwallTypes' => [
            open20\socialwall\utility\Social::LIVE_WALL => "Social wall",
            open20\socialwall\utility\Social::PICKED_POSTS_WALL => "Contenuti social correlati",
        ],
  

Configurable parameters

• profile_pictures_url - array
  Instagram apis doesn't return the url of a profile image when data from Instagram are fetched. The url of the profile image needs to be provided manually.
  To display the profile picture of an instagram account for every type of socialwall, you need to set the following parameters in the desired params.php or params-local.php file:

    ...
        'instagram' => [
            ...
            'profile_pictures_url' => [
                "<IG ACCOUNT ID>" => '<URL OF PROFILE IMAGE>',
                "123456" => 'https://picsum.photos/500',
            ],
            ...
        ]
    ...
  

How to configure social tokens

You can use the cruds (available only to users who can SOCIALWALL_ADMIN) at:

<YOUR APP URL>/socialwall/socialwall-tokens/

You can add an account using the "Aggiungi Account" button, chosing a name for the token type that will be displayed in the forms (e.g. Facebook) and the token type that will be added.
Clicking on "Crea" button:

• for Facebook, there will be a "Facebook Login" link that will bring to the Facebook Login to add facebook accounts to the application. You need to complete all the forms/steps displayed (also manually selecting the accounts that will be used inside the app)
• for Instagram, there will be an "Instagram Login" link that will bring to the Instagram Login. The account used during the Instagram login will be automatically used in the app
• for Twitter, a "Nome Utente Twitter" and "Token Twitter" field will be displayed. You can copy and paste desired values in them

How to renew social tokens

AT THE MOMENT, the tokens needs to be renewed manually.
The expiration dates for Facebook and Instagram are displayed in the socialwall-tokens crud explained above.
REMEMBER to manually renew social network tokens before the expiration date.
To renew tokens, you can do it via the socialwall-tokens crud. You don't need to create a new account, you can just edit a previously created account:

• in the socialwall-tokens index page, edit (update) a desired account
• follow the login procedure again if available or update/fill the tokens fields
• for Facebook and Instagram, the new expiration date will be automatically updated

Choose posts for socialwall

You need to create a widget/link to the socialwall-posts crud available here:

<YOUR APP URL>/socialwall/socialwall-posts/

This will bring to the "Asset Social" feature.
You can import posts via the "Carica" button: this will allow to search and add static posts in the app.
Imported posts can be edited immediately after importing them or using the edit/update function available in the index page of the "Asset Social" page/list.

Available widgets

To try to avoid errors, the widgets are automatically displayed only if the model set as param in the widgets are in the modulesIdClassMapEnable config array explained above.

SocialwallSelectorWidget
Widget for forms to allow creating the desired type of socialwall to be displayed in a view or in a frontend page. To use it you need to include widget in the code as below:

<?php if (!is_null(\Yii::$app->getModule('socialwall'))) : ?>


<?= 
    \open20\socialwall\widgets\SocialwallSelectorWidget::widget([
        'form' => $form, 
        'model' => $model, 
        'attribute' => 'socialwall'
    ]); 
?>

<?php endif; ?>

SocialwallFromModelWidget
Widget for views/frontend pages that will display a socialwall set in the form.
This widget will render automatically the selected type of socialwall (live or picked posts) set in the form.

<?php if (!is_null(\Yii::$app->getModule('socialwall'))) : ?>

<?php \frontend\modules\socialwall\assets\ModuleSocialWallAsset::register($this); ?>

<div class="row">
    <div class="col-md-12">
        <?=
            \open20\socialwall\widgets\SocialwallFromModelWidget::widget([
                'model' => $model,
            ]);
        ?>
    </div>
</div>

<?php endif; ?>

Available cron functions

If you want to automatically fetch contents from Instagram and to rebuild automatically live walls, you can create a couple of crons to fetch contents when needed.
It's recommended to run the Instagram fetch cron BEFORE the socialwall live wall rebuild because, as default, the Instagram posts used inside the module are those which are cached in the app database.
In your console folder, you can create a SocialwallController.php file in controllers folder as below:

<?php

namespace console\controllers;

class SocialwallController extends \open20\socialwall\controllers\ConsoleController
{

}

The available functions will be:

• actionUpdateInstagramCache
  To fetch data from Instagram and cache it in the database
• actionUpdateSocialwallLiveCache
  To automatically rebuild live walls that a user chose to be automatically updated

To fetch data via cron/command line, you can then use the following commands:

For fetching and caching Instagram posts:

yii socialwall/update-instagram-cache   

For automatically rebuilding live walls (if selected by user):

yii socialwall/update-socialwall-live-cache