Ajouter un module dans HomeLanding

PHP
HTML
CSS
JS


Cette procédure est applicable à partir de la version de PHPBoost

Pour la simplification du tutoriel, les exemples de scripts et noms des fichiers sont définis pour un module nommé Blog, il faudra donc adapter le nom et les requêtes à ceux du module ajouté.

Deux procédures d'ajout



Ajouter le module avant l'instalation de HomeLanding
Il sera ajouté et disponible dans la liste des modules compatibles dès l'installation de HomeLanding.

Ajouter le module après l'installation de HomeLanding
Il sera détecté automatiquement et une nouvelle page 
Ajouter des éléments
apparait dans la configuration de HomeLanding, permettant d'ajouter le module dans la liste des modules compatibles.

Fichiers à ajouter dans HomeLanding



À quelques exceptions près, les scripts du module à ajouter sont à déclarer dans des fichiers séparés, qui sont automatiquement chargés dans le bon fichier de HomeLanding et au bon endroit. Ainsi une éventuelle mise à jour de HomeLanding n'impactera pas les modifications apportées.
Pour les scripts ajoutés dans les sous-dossiers de 
/HomeLanding/additional/
, la récupération des scripts se fait par une reconnaissance de présence de fichiers. Le nom de ces fichiers est arbitraire, seul compte leur contenu selon leur emplacement. Ainsi on pourra ajouter au choix


Déclaration de la compatibilité du module avec HomeLanding



Cela permet


Config.ini du module
Dans le fichier 
/blog/config.ini

Ajouter 
homelanding
dans la liste des 
features
du module.
Si l'option 
features
n'existe pas dans le 
config.ini
du module, il suffit de l'ajouter.
Code TEXT : 
features = "homelanding"


À ce stade, placez vous sur la page



Dans le menu du haut, cliquez sur 
Ajouter des éléments
. Une fois sur cette page, passez aux étapes suivantes SANS VALIDER.

L'ajout des fichiers va rendre la page configuration inaccessible, d'où l'utilité de se rendre sur la page d'ajout, avant. Si vous êtes amenés à en sortir, vous pouvez la rejoindre avec l'adresse 
/HomeLanding/admin/add
ou 
/HomeLanding/?url=/admin/add/
selon l'état de votre 
url_rewriting


!! IMPORTANT !!


La suite de cette procédure prévoit l'affichage du contenu du module sans distinction de catégorie.
Pour ajouter un module qui permettra d'afficher séparément le contenu de ses catégories, il faut utiliser les scripts de l'exemple donné sur cette annexe

Déclaration du module dans l'initialisation de la liste des modules compatibles



/HomeLanding/additional/add/
Cette déclaration est nécessaire uniquement si le module HomeLanding est déjà installé.
Créer un fichier 
/HomeLanding/additional/add/AdditionalAdd.php

Code PHP : 
<?php
$module = new HomeLandingModule();
$module->set_module_id(HomeLandingBlog::MODULE_BLOG);
$module->set_phpboost_module_id(HomeLandingBlog::MODULE_BLOG);
$module->hide();
$modules[] = $module->get_properties();
?>


/HomeLanding/additional/init/
Cette déclaration est nécessaire si le module HomeLanding n'est pas déjà installé, ou s'il est amené à être réinstallé.
Créer un fichier 
/HomeLanding/additional/add/AdditionalInit.php

Code PHP : 
<?php
$module = new HomeLandingModule();
$module->set_module_id(HomeLandingBlog::MODULE_BLOG);
$module->set_phpboost_module_id(HomeLandingBlog::MODULE_BLOG);
$module->hide();
$modules[] = $module->get_properties();
?>


Formulaire pour le module



/HomeLanding/additional/form/
Les champs de formulaire pour le module dans la configuration de HomeLanding
Créer le fichier 
/HomeLanding/additional/form/AdditionalForm.php

Code PHP : 
<?php
if ($this->modules[HomeLandingBlog::MODULE_BLOG]->is_active())
    {
        $fieldset_blog = new FormFieldsetMultitabsHTML('admin_blog', $this->lang['homelanding.module.display'] . ModulesManager::get_module($this->modules[HomeLandingBlog::MODULE_BLOG]->get_module_id())->get_configuration()->get_name(),
            array('css_class' => 'tabs tabs-animation')
        );
        $form->add_fieldset($fieldset_blog);
        $fieldset_blog->add_field(new FormFieldCheckbox('blog_enabled', $this->lang['homelanding.show.full.module'], $this->modules[HomeLandingBlog::MODULE_BLOG]->is_displayed(),
            array(
                'class'=> 'custom-checkbox',
                'events' => array('click' => '
                    if (HTMLForms.getField("blog_enabled").getValue()) {
                        HTMLForms.getField("blog_limit").enable();
                    } else {
                        HTMLForms.getField("blog_limit").disable();
                    }'
                )
            )
        ));
        $fieldset_blog->add_field(new FormFieldNumberEditor('blog_limit', $this->lang['homelanding.items.number'], $this->modules[HomeLandingBlog::MODULE_BLOG]->get_elements_number_displayed(),
            array(
                'min' => 1, 'max' => 100,
                'hidden' => !$this->modules[HomeLandingBlog::MODULE_BLOG]->is_displayed()
            ),
            array(new FormFieldConstraintIntegerRange(1, 100))
        ));
}
?>


/HomeLanding/additional/save/
La sauvegarde des choix effectués dans le formulaire
Créer le fichier 
/HomeLanding/additional/save/AdditionalSave.php

Code PHP : 
<?php
if ($this->modules[HomeLandingBlog::MODULE_BLOG]->is_active())
    {
        if ($this->form->get_value('blog_enabled'))
        {
            $this->modules[HomeLandingBlog::MODULE_BLOG]->display();
            $this->modules[HomeLandingBlog::MODULE_BLOG]->set_elements_number_displayed($this->form->get_value('blog_limit'));
        }
        else
            $this->modules[HomeLandingBlog::MODULE_BLOG]->hide();
}
?>


/HomeLanding/additional/submit/
L'état d'affichage des champs après validation du formulaire.
Créer le fichier 
/HomeLanding/additional/submit/AdditionalSubmit.php

Code PHP : 
<?php
if ($this->modules[HomeLandingBlog::MODULE_BLOG]->is_active())
            {
                $this->form->get_field_by_id('blog_limit')->set_hidden(!$this->modules[HomeLandingBlog::MODULE_BLOG]->is_displayed());
}
?>


Récupération de données et templates



Deux cas de module sont possibles :

Dans les deux cas il faut ajouter la variable d'affichage de template dans le template principal de HomeLanding :
/HomeLanding/templates/home.tpl
Si une mise à jour de PHPBoost ou du module Page d'accueil implique ce fichier, il faudra à nouveau reproduire cette modification
Chercher 
// Additional modules

A la suite, ajouter
Code TPL : 
# INCLUDE  BLOG #


Les modules "core"



/HomeLanding/additional/home/
Déclaration de la variable d'affichage du module
Créer un fichier 
/HomeLanding/additional/home/AdditionalHome.php

Code PHP : 
<?php
if ($this->modules[HomeLandingBlog::MODULE_BLOG]->is_displayed() && CategoriesAuthorizationsService::check_authorizations(Category::ROOT_CATEGORY, HomeLandingBlog::MODULE_BLOG)->read())
            $this->view->put('BLOG', HomeLandingDisplayItems::build_view(HomeLandingBlog::MODULE_BLOG));
?>


Les modules "base"



/HomeLanding/services/modules/
Récupération des données et déclaration du template du module
Créer le fichier 
/HomeLanding/services/modules/HomeLandingBlog.class.php

Code PHP : 
<?php
class HomeLandingBlog
{
const MODULE_BLOG = "blog";
public static function get_blog_view()
    {
        $now = new Date();
        $module_config = BlogConfig::load();
        $home_config   = HomeLandingConfig::load();
        $modules       = HomeLandingModulesList::load();
        $module_name   = self::MODULE_BLOG;
        $theme_id = AppContext::get_current_user()->get_theme();
        if (file_exists(PATH_TO_ROOT . '/templates/' . $theme_id . '/modules/HomeLanding/pagecontent/' . $module_name . '.tpl'))
            $view = new FileTemplate('/templates/' . $theme_id . '/modules/HomeLanding/pagecontent/' . $module_name . '.tpl');
        elseif (file_exists(PATH_TO_ROOT . '/HomeLanding/templates/pagecontent/' . $module_name . '.tpl'))
            $view = new FileTemplate('/HomeLanding/templates/pagecontent/' . $module_name . '.tpl');
        else
            $view = new FileTemplate('HomeLanding/pagecontent/items.tpl');
        $home_lang = LangLoader::get_module_langs('HomeLanding');
        $module_lang = LangLoader::get_module_langs($module_name);
        $view->add_lang(array_merge(LangLoader::get_all_langs(), $home_lang, $module_lang));
        $authorized_categories = CategoriesService::get_authorized_categories(Category::ROOT_CATEGORY, $module_config->is_summary_displayed_to_guests(), $module_name);
        $result = PersistenceContext::get_querier()->select('SELECT blog.*, member.*, cat.rewrited_name AS rewrited_name_cat
        FROM ' . PREFIX . 'blog blog
        LEFT JOIN ' . PREFIX . 'blog_cats cat ON cat.id = blog.id_category
        LEFT JOIN ' . DB_TABLE_MEMBER . ' member ON member.user_id = blog.author_user_id
        WHERE (published = 1 OR (published = 2 AND publishing_start_date < :timestamp_now AND (publishing_end_date > :timestamp_now OR publishing_end_date = 0))) AND id_category IN :authorized_categories
        ORDER BY blog.update_date DESC
        LIMIT :blog_limit', array(
            'authorized_categories' => $authorized_categories,
            'user_id' => AppContext::get_current_user()->get_id(),
            'timestamp_now' => $now->get_timestamp(),
            'blog_limit' => $modules[$module_name]->get_elements_number_displayed()
        ));
        $view->put_all(array(
            'C_NO_ITEM'       => $result->get_rows_count() == 0,
            'C_VIEWS_NUMBER'  => true,
            'C_GRID_VIEW'     => $module_config->get_display_type() == BlogConfig::GRID_VIEW,
            'C_TABLE_VIEW'    => $module_config->get_display_type() == BlogConfig::TABLE_VIEW,
            'MODULE_NAME'     => $module_name,
            'MODULE_POSITION' => $home_config->get_module_position_by_id($module_name),
            'ITEMS_PER_ROW'   => $module_config->get_items_per_row(),
            'L_MODULE_TITLE'  => ModulesManager::get_module($module_name)->get_configuration()->get_name(),
        ));
        while ($row = $result->fetch())
        {
            $item = new BlogItem();
            $item->set_properties($row);
            $view->assign_block_vars('items', array_merge($item->get_array_tpl_vars(), array(
                'C_SEVERAL_VIEWS' => $item->get_views_number() > 1,
            )));
        }
        $result->dispose();
        return $view;
    }
}
?>


/HomeLanding/additional/home/
Déclaration de la variable d'affichage du module dans le template principal de HomeLanding
Créer un fichier 
/HomeLanding/additional/home/AdditionalHome.php

Code PHP : 
<?php
if ($this->modules[HomeLandingBlog::MODULE_BLOG]->is_displayed() && CategoriesAuthorizationsService::check_authorizations(Category::ROOT_CATEGORY, HomeLandingBlog::MODULE_BLOG)->read())
            $this->view->put('BLOG', HomeLandingBlog::get_blog_view(HomeLandingBlog::MODULE_BLOG));
?>


/HomeLanding/templates/pagecontent/
Si les variables de templates du modules sont identiques aux variables de templates communes à tous les modules, le fichier.tpl /HomeLanding/templates/pagecontent/item.tpl peut être utilisé et il n'y a donc pas besoin de template spécifique pour ce module

Sinon, ou si on veut utiliser un template différent, il faut créer un fichier tpl au nom de la constante du module, 
/HomeLanding/templates/pagecontent/blog.tpl
dans lequel il faut à minima déclarer la variable de position pour pouvoir placer le module où l'on veut sur la page d'accueil:
Code TPL : 
<div class="sub-section" style="order: {MODULE_POSITION};">
...
</div>


Au final, un seul des fichiers originels de HomeLanding est modifié: /
/HomeLanding/templates/home.tpl
. Il faudra donc en faire une sauvegarde avant d'appliquer une future mise à jour de HomeLanding et réappliquer les modifications sur ce fichier

Une astuce consiste à surcharger 
home.tpl
dans le thème utilisé

  • templates
  • +Nom_Du_Theme
  • ++modules
  • +++HomeLanding
  • ++++home.tpl



Finaliser l'ajout du module



Maintenant que tous les fichiers sont créés, il faut ajouter le module via la configuration de HomeLanding sur la page 
Ajouter des éléments

Vous pouvez maintenant 
Valider