Components

This guide will help developers understand what is a component and how to use them.

What is a component?

A component is a certain element or block of a design that can be edited and reused multiple times in a project. For example: tabs, buttons, accordion, etc.

Each component consists of:

• A PHP template that has a dynamic html layout, depending on the variables passed to this template. It is located in the _core/stm-lms-templates/components folder.

• SCSS style file, which after compilation is connected to the php template of the component and is in charge of the adaptive display of the component on the page. It is located in the _core/assets/scss/components folder.

• In some cases - a Javascript file with code, which is connected to the php template of the component is necessary for the correct operation of the component. It is located in the _core/assets/es6/components folder.

How to use the component on a page

The component template is added to the page through the STM_LMS_Templates::show_lms_template() template insertion function;

The path to the component is written into the function (by default, the path always starts from the folder with templates _core/stm-lms-templates) and the variables necessary for the correct operation and display of the component are passed in an array.

Important: This guide has PHP code and is meant for developers. We share the code as a friendly gesture but don't provide support for code customization or third-party development.

If necessary, you can also insert the component using any other function that allows you to insert PHP templates and pass variables into them.

Example of inserting a template into a page:

<?php
STM_LMS_Templates::show_lms_template(
    'components/curriculum-accordion',
        array(
            'course_id'         => $post_id,
            'current_lesson_id' => $item_id,
            'user'              => $user,
            'curriculum'        => $curriculum,
            'dark_mode'         => false,
    )
);
?>

Styles and Javascript for the component

The necessary styles and javascript files are already connected in the component template.

Some components contain javascript and some do not. This is to avoid conflicts when the component is used differently on the page.

In case the component does not contain javascript, you will need to connect it to the page where you plan to use the component.

An example of a component template:

<?php
/**
 * @var string $title
 * @var int $id
 * @var boolean $dark_mode
 *
 * masterstudy-switch-button_active - for active state
 * masterstudy-next-prev-button_dark-mode - for dark mode
 */
wp_enqueue_style( 'masterstudy-switch-button', STM_LMS_URL . '/assets/css/components/switch-button.css', null, MS_LMS_VERSION );
?>

<button class="masterstudy-switch-button <?php echo esc_attr( $dark_mode ? 'masterstudy-switch-button_dark-mode' : '' ); ?>" data-id="<?php echo esc_attr( $id ); ?>">
	<span class="masterstudy-switch-button__title"><?php echo esc_html( $title ); ?></span>
</button>

How to add alignment, indentation, and other situational styles to a component

It's important to realize that a component is a template that is overused in different parts of the project. You cannot add situational styles such as indentation, alignment, etc. to the code of the component itself. It should always be inserted in "clean form", otherwise there will inevitably be conflicts when reusing it.

If you need to add such styles, make a wrapper for the component (a container in which the component will be inserted), and set all the necessary styles to that container.

Example:

<?php
if ( $progress > 0 ) {
    ?>
    <div class="masterstudy-course-player-curriculum__progress">
        <?php
        STM_LMS_Templates::show_lms_template(
        'components/progress',
            array(
                'title'     => __( 'Course progress', 'masterstudy-lms-learning-management-system' ),
                'progress'  => $progress,hp
                'dark_mode' => false,
            )
        );
        ?>
    </div>
<?php } ?>

.masterstudy-course-player-curriculum__progress {
    display: flex;
    justify-content: center;
    width: 100%;
    padding: 20px 30px;
    margin: 20px 10px 0 0;
}

Component modifiers

To change the style or state of a component, you add a CSS modifier class. The modifier class is added in the component's template, based on the variables you pass in (for example: dark_mode: false, style: 'nav-sm').

Example:

<?php
STM_LMS_Templates::show_lms_template(
    'components/tabs',
    array(
        'items' => array(
            array(
                'id'    => 'lesson',
                'title' => __( 'Lesson', 'masterstudy-lms-learning-management-system' ),
            ),
            array(
                'id'    => 'materials',
                'title' => __( 'Materials', 'masterstudy-lms-learning-management-system' ),
            ),
        ),
        'style'            => 'nav-sm',
        'active_tab_index' => 0,
        'dark_mode'        => false,
    )
);
?>

<?php

/**
 * @var array $items
 * @var string $style
 * @var int $active_tab_index
 * @var boolean $dark_mode
 *
 * masterstudy-tabs_dark-mode - for dark mode
 * masterstudy-tabs__item_active - for item active state
 * masterstudy-tabs_style-default|nav-sm|nav-md - for tabs style change
 */

wp_enqueue_style( 'masterstudy-tabs', STM_LMS_URL . '/assets/css/components/tabs.css', null, MS_LMS_VERSION );
?>

<ul class="masterstudy-tabs <?php echo esc_attr( $dark_mode ? 'masterstudy-tabs_dark-mode' : '' ); ?> <?php echo esc_attr( 'masterstudy-tabs_style-' . $style ); ?>">
    <?php foreach ( $items as $index => $item ) { ?>
        <li class="masterstudy-tabs__item <?php echo $active_tab_index === $index ? 'masterstudy-tabs__item_active' : ''; ?>" data-id="<?php echo esc_attr( $item['id'] ); ?>">
            <?php echo esc_html( $item['title'] ); ?>
        </li>
    <?php } ?>
</ul>

But sometimes there are cases when you need to modify a component via javascript, like changing the style, or color theme of the component or highlighting the active tab when you click on it. For such cases, all the names of modifier classes are contained in the comments at the top of the component template. You can assign them via custom JavaScript code on the page.

Example:

// tabs toggler depending on the visibility in the window
$('.masterstudy-course-player-content__wrapper').on('scroll', function() {
    let materialsTab = $('.masterstudy-course-player-header .masterstudy-tabs__item[data-id="materials"]'),
        lessonTab = $('.masterstudy-course-player-header .masterstudy-tabs__item[data-id="lesson"]'),
        materialsInView = isElementInView('.masterstudy-course-player-lesson-materials');
            
    if (materialsInView) {
        materialsTab.addClass('masterstudy-tabs__item_active');
        lessonTab.removeClass('masterstudy-tabs__item_active');
    } else {
        materialsTab.removeClass('masterstudy-tabs__item_active');
        lessonTab.addClass('masterstudy-tabs__item_active');
    }
});

function isElementInView(selector) {
    let element = document.querySelector(selector),
        rect = element.getBoundingClientRect();
    return (
        rect.top >= 0 &&
        rect.left >= 0 &&
        rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) &&
        rect.right <= (window.innerWidth || document.documentElement.clientWidth)
    );
}