Создание полноценного виджета для Yii2

[GHopper]

/*голос из будущего*/
Вот что получилось:


Ссылка на GitHub: https://github.com/GHopperMSK/svgMap
---

Здравствуйте.

Я веб-программист с многолетним стажем, работающий в компании над сложным интересным проектом. У нас свой git-сервер и свой фреймворк.

В качестве расширения кругозора хочу инвестировать часть свободного времени в изучение Yii2. Интересует не простой Hello word после прочтения документации, а что-то рабочее и реюзабильное. Парралельно хотелось бы разобраться с github (полноценный проект со всеми "модными иконками", packagist, и совместная работа над проектом).

В общем, предстоит путь долгий и тернистый. Разбил его на этапы:

1. Постановка задачи
2. Реализация исходного проекта
3. Размещение на github
4. Поддержка и развитие

Пункт первый выполнен. Хочу создать ползеный виджет, функционал которого вы можете оценить в гите (т.е. на 3 стадии). Рабочее название "map".

В данный момент идет работа над пунктом вторым. Виджет написан, он интегрируется во view и выполняет свой функционал. Имеются следующие вопросы:

1. В виджете есть assets (css, js) и view. Соответственно структура директорий следующая

Код: Выделить всё

@app/components/map/mapWidget.php
@app/components/map/mapWidgetAsset.php
@app/components/map/assets
@app/components/map/assets/css
@app/components/map/assets/js
@app/components/map/views

Насколько это правильно?

2. Namespace

Код: Выделить всё

namespace app\components\map;

Подозреваю что с таким namespace скоро возникнут конфликты в большом проекте. Как принято разрешать такие ситуации в больших проектах? Использовать имя пользователя?

Код: Выделить всё

namespace app\components\ghopper\map;

3. Структура git-ропозитория. Что должно быть помещенов git (как я понимаю только дирретория components/map) и какая структура всего репозитория должна быть (исходники, тесты, примеры и т.п.).

4. Пару строк по офрмлению кода. Как я понимаю, в Yii2 принят некий формат, которому желательно следовать. Есть ли тулза, которая бы проверяла формат? Где почитать рекомендации? Какие-то сложные инструкции в phpDoc или все ограничивается описанием методов и членов?

Еще раз обращу внимание, что в результате п.2 хочу получить код, готовый к размещению на github, который будет удобно ипользовать в других проектах через composer. Поэтому такое внимание структуре директорий и namespace.

[ElisDN]

1. Нормальная. Но если будете добавлять тесты и документацию, то лучше сделать папки src, tests и docs вместо скидывания всего в корень.

2. Все обычно публикуют с неймспейсом <ник>/<библиотека>

Код: Выделить всё

namespace ghopper\map;

и похожим именем пакета для загрузки:

Код: Выделить всё

composer require ghopper/map

Но так как делаете для Yii, то можно назвать с префиксом:

Код: Выделить всё

composer require ghopper/yii2-map

Если будете делать просто PHP-компоненты не для Yii, то лучше называть неймспейсы с большой буквы:

Код: Выделить всё

namespace ElisDN\Hydrator;

а имя пакета оставить с маленькой:

Код: Выделить всё

composer require elisdn/php-hydrator

Так как неймспейсы с маленькой больше практически никто кроме Yii не называет.

3. Для примера:

http://www.elisdn.ru/blog/88/seo-servic ... extensions
http://www.elisdn.ru/blog/91/gii-fixture-generator
http://www.elisdn.ru/blog/111/yii2-composite-forms

4. Используются стили кодирования из общепринятых PSR:

http://www.php-fig.org/psr/
https://svyatoslav.biz/misc/psr_translation/

Есть PHP Code Sniffer. Ставим в проект:

Код: Выделить всё

composer require --dev squizlabs/php_codesniffer

В корень проекта добавляем файл phpcs.xml.dist с примерной конфигурацией:

Код: Выделить всё

<?xml version="1.0"?>
<ruleset name="Coding standard">
    <description>Coding standard</description>

    <!-- display progress -->
    <arg value="p"/>
    <arg name="colors"/>

    <!-- inherit rules from: -->
    <rule ref="PSR2"/>
    <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
    <rule ref="Squiz.WhiteSpace.SuperfluousWhitespace">
        <properties>
            <property name="ignoreBlankLines" value="false"/>
        </properties>
    </rule>

    <!-- Paths to check -->
    <file>src</file>
</ruleset>

Запускаем проверку:

Код: Выделить всё

vendor/bin/phpcs

Запускаем автоисправление:

Код: Выделить всё

vendor/bin/phpcbf

Также если программируете в PhpStorm, то можно открыть любой файл и нажать Ctrl+Alt+L.

В качестве расширения кругозора хочу инвестировать часть свободного времени в изучение Yii2.

Один Yii2 для кругозора не очень полезен, так как с ним Вы не научитесь пользоваться Composer-ом, конструкторами классов, контейнером внедрения зависимостей, рекомендациями PSR, исключениями, декомпозицией, шаблонизаторами, сборщиками фронтенда. Да и он уже три года особо не обновлялся и новых вещей в нём нет. Поэтому помимо него посмотрите и другие фреймворки.

[GHopper]

Спасибо за ответ.

Ок. Сырой проект создан. В git загружен.
Теперь давайте обсудим чуть больше конкретики.



Идея виджета - svg карта, создающаяся на основе входных данных.
Планирую получать данные из php-массива, js-файла либо запрашивать json по адресу. Сама карта будет выступать инструментом навигации по разделам, выбором региона, вызова js-функций и др. Т.е. такой инстумент, в который передаем paths с параметрами и получаем svg с заданными в параметрах событиями.
В качестве пример - карта России, позволяющая перейти в выбранный регион.

Все добро размещается по адресу https://github.com/GHopperMSK/svgMap

Палн ближайших работ:
- добавить анимацию при наведении курсора мыши
- добить обработчик клика
- добавить всплывающие подсказки

Никуда не тороплюсь, занимаюсь в образовательных целях, сроков вообще нет. Более того, frontend вообще не моя сфера интересов, поэтому сроки будут ограничены в т.ч. изучением кучи всего смежного (а это и формат svg, и git, и js и т.п.).

Вопросы:
1. Версионирование. Как автоматически увеличивать версии в репозитории? Сталкивался с тэгами, но было бы здоров автоматически добавлять версию непосредственно в phpDoc кода.

2. Как выполнить

Код: Выделить всё

var map = new svgMap({
    svgId : 'mapSVG',
    states: ruStates
});

непосредственно в коде шаблона? Столкнулся с вопросом последовательности загрузки различных js-модулей.

3. Во многих гит-репозиториях вижу разные иконки, которые показывают "крутость проета". Покрытие тестами, лицензию и др. Где почитать про это?

4. Лицензия. Никогда не сталкивался. Какую указывать, чтобы люди безвозмездно брали и пользовались?

5. В файле svgMapWidgetAsset есть код:

Код: Выделить всё

    public function init()
    {
        $this->sourcePath = '@vendor/ghopper/svg-map/src/assets';

        parent::init();
    }

Расхаркодить это как-то можно? Нужно? Подозреваю что здесь может быть источник ошибок.

P.S. Попытался добавить скриншот виджета, получил ошибку в DevTools:

Код: Выделить всё

Failed to load resource: the server responded with a status of 404 (Not Found)
Failed to load resource: the server responded with a status of 404 (Not Found)
plupload.css Failed to load resource: the server responded with a status of 404 (Not Found)

[ElisDN]

Уберите префиксы из классов. Вместо svgMapWidget называйте MapWidget.
Уберите закрывающий "?>" из файлов с классами.

1. Просто ставьте теги:

Код: Выделить всё

git tag 1.0.0
git push --tag

версия в PHPDoc не нужна.

2. Через registerJs():

Код: Выделить всё

<?php $this->registerJs("
    var map = new svgMap({
        svgId : 'mapSVG',
        states: ruStates
    });
"); ?>

3. Прямо в этих репозиториях взять иконки из README.md и позаходить на сайты, на которые они ведут при клике. А так на примере Yii2 посмотреть файлы конфигурации сервисов вроде .scrutinizer.yml и .travis.yml.

4. Скопируйте LICENCE.md у Yii2 или любого чужого компонента и поменяйте имена на свои. Удобнее всего BSD-3 и MIT.

5. Вместо метода init() присвойте сразу полю:

Код: Выделить всё

public $sourcePath = '@vendor/ghopper/svg-map/src/assets';

Расхаркоживать нет смысла, так как папка внутри vendor сама никак не поменяется.

P.S. Попытался добавить скриншот виджета, получил ошибку в DevTools

Загрузите на какой-нибудь хостинг изображений и вставьте сюда адрес.

[GHopper]

Название хотелось бы все-таки оставить svgMap, т.к. не просто карта, а карта svg-данных (т.е. может быть график, изображение, карта и др).

Несколько вопросов:

1. Удаление закрывающего "?>" чем обусловлено? С 1995 года люди закрывают, а здесь выясняется что все зря )

2. Моим следующим шагом планируется кастомизация виджета. Одно из направлений кастомизации - источник данных. Хочу добавить возможность передавать php-массив, адрес json и (как сейчас реализовано) js-файл. Для этого мне необходимо передвать в svgMapWidgetAsset параметры, чтобы подключать/не подключать js-файл и, если уж подключать, то передать название файла (т.к., например, может быть несколько стран и в зависимости от переданного параметра будет генерироваться карта выбранной страны).
Как это реализовать? На ум приходит только одна мысль - переопределить метод svgMapWidgetAsset::register()? Но метод этот статический...

[ElisDN]

Тогда назовите SvgMap, чтобы все классы были с большой.

1. Обусловнено борьбой со случайной отправкой пробела, который может оказаться прсле закрытия в файле.

[GHopper]

Вполне годный аргумент! Увы, по второму вопросу так и не получил ответ. Постараюсь дать пояснения:

1. Виджет строит svg-карту по переданным ему данным. На данный момнт я хочу реализовать следующие источники:
а) php-массив (как следствие данные из БД)
б) ссылка на json (как следствие работа с REST)
в) js-файл (массивы могут быть огромными, поэтому хочется подключать "на лету" только нужные)

Пример параметров виджета:

Код: Выделить всё

    echo SvgMapWidget::widget([
        'data' => [
            'type' => SvgMapWidget::DATA_SOURCE_JS_FILE,
            'source' => 'russia.js',
        ]
    ]);

Все js и css подгружаются через SvgMapWidgetAsset:

Код: Выделить всё

class SvgMapWidgetAsset extends AssetBundle
{
    public $sourcePath;

    public $css = [
        'css/svg-map.css'
    ];
    
    public $js = [
        'js/russia.js',
        'js/svg-map.js',
    ];

    public $depends = [
        'yii\web\JqueryAsset',
    ];

    public function init()
    {
        $this->sourcePath = '@vendor/ghopper/svg-map/src/assets';

        parent::init();
    }
}

Как видим, среди прочего, захардкожен js-файл russia.js. Но для удобства, с виджетом может идти и, например, china.js. Так вот, как перенести параметр из SvgMapWidget в SvgMapWidgetAsset, чтобы динамически подключать нужные файлы?

P.S. сейчас вспомнил про перенос инициализации sourcePath из метода init(). Это просто общепринятое правило или тоже имеет свое обоснование?

2. Виджет имеет свой шаблон. Хотелось бы сделать его универсальным в плане поличества экземпляров. Сейчас в коде захардкожены id дивов, в которые мы будем аппендить созданные структуры:

Код: Выделить всё

<div class="svg_map">
    <div id="tooltip">tooltip</div>
    <svg id="mapSVG" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" />
</div>

<?php
$this->registerJs("
    var map = new SvgMap({
        svgId : 'mapSVG',
        toolTipId: 'tooltip',
        states: ruStates
    });
");
?>

Это, опять же, неправильно. Хочу присваивать этим дивам уникальный id, чтобы на странице можно было размещать любое кол-во виджетов. Соответственно, я могу добавить рандомное число в каждый id, но это как-то выглядит делитантски. Как правильно решить этот вопрос?

[caHek2x]

насчет id
например как сделано в ActiveForm yii2

ActiveForm наследуется от Widget

Код: Выделить всё

public function init()
    {
        if (!isset($this->options['id'])) {
            $this->options['id'] = $this->getId();
        }
        ...

а getId это уже метод из класса Widget:

Код: Выделить всё

    
    private $_id;
    public static $autoIdPrefix = 'w';
    public static $counter = 0;

    public function getId($autoGenerate = true)
    {
        if ($autoGenerate && $this->_id === null) {
            $this->_id = static::$autoIdPrefix . static::$counter++;
        }

        return $this->_id;
    }

[maleks]

Как видим, среди прочего, захардкожен js-файл russia.js. Но для удобства, с виджетом может идти и, например, china.js. Так вот, как перенести параметр из SvgMapWidget в SvgMapWidgetAsset, чтобы динамически подключать нужные файлы?

Вы можете для вот этих - russia.js, china.js - сделать по отдельному AssetBundle, которые будут зависеть от вашего SvgMapWidgetAsset (в котором только svg-map.js). А в настройках виджета предусмотреть св-во 'assetBundle', которое уже можно установить при вызове виджета

[GHopper]

Вы можете для вот этих - russia.js, china.js - сделать по отдельному AssetBundle, которые будут зависеть от вашего SvgMapWidgetAsset (в котором только svg-map.js). А в настройках виджета предусмотреть св-во 'assetBundle', которое уже можно установить при вызове виджета

Спасибо за ответ. Теперь у меня есть хоть какое-то решение.
Признаюсь честно, оно кажется мне не совсем удобным, т.к. придется захардкодить все имеющиеся файлы в AssetBundle. Более того - с виджетом идет набор "популярных карт", но ничто не должно мешать добавить свою. И в этом случае нужно будет передавать в AssetBundle ссылку на файл из публичной web-дирректории.

В общем круто, что решение нашлось. Но есть еще над чем подумать...

[GHopper]

Я пришел к выводу, что от идеи с динамическим подключение js-файлов можно отказаться. Ни такая уж это и килл-фича. Пляшем дальше.

Обновил гит-репозиторий: https://github.com/GHopperMSK/svgMap

Продолжу с вопросами:

1. Карту рисует js-класс:

Код: Выделить всё

var SvgMap = function(options) {

    var svg;
    var type;
    var toolTip;
    var box = {
        x: 0,
        y: 0,
        height: 0,
        width: 0
    };

    var root = this;

    /*
     * Constructor
     */
    this.construct = function(options){

        ['id','type','data'].forEach(function (param) {
            if(typeof options[param] === 'undefined') {
                throw new Error(param + ' parameter is missed');
            }
        });

        root.svg = $('#mapSVG'+options.id).get(0);
        root.type = options.type;
        root.toolTip = $('#tooltip'+options.id).get(0);

        var json = {};
        if (root.type === 'json') {
            json = options.data;
        } else {
            $.ajax({
                url: options.data,
                method: 'GET'
            }).then(function(data) {
                console.log(data);
            });
        }

        // TODO: validate json
        draw(root.svg, json);
    };

    /*
     * Draws the paths from array
     */
    var draw = function(svg, data) {
        $.each(data, function( index, value) {
            var path = document.createElementNS('http://www.w3.org/2000/svg',"path");
            path.setAttributeNS( null, "id", value.id);
            path.setAttributeNS( null, "d", value.d);
            path.setAttributeNS( null, "title", value.title);
            path.addEventListener("mousemove", mouseMove);
            path.addEventListener("mouseover", mouseOver);
            path.addEventListener("mouseout", mouseOut);
            path.addEventListener('click', mouseClick);
            svg.appendChild(path);
        });
        adaptViewBox(svg);
    };

    var mouseMove = function(e) {
        root.toolTip.style.left = e.offsetX + 'px';
        root.toolTip.style.bottom = e.offsetY + 'px';
    }

    var mouseOver = function(e) {
        root.toolTip.style.visibility = "visible";
        root.toolTip.innerHTML = createToolTipContext($(this));
    }

    var mouseOut = function() {
        root.toolTip.style.visibility = "hidden";
        root.toolTip.innerHTML = $(this).attr('');
    }

    var mouseClick = function() {
        alert($(this).attr('id') + '-' + $(this).attr('title'));
    }

    var createToolTipContext = function(path) {
        return path.attr('title');
    }

    /*
     * Adapts dimension of SVG according it paths
     */
    var adaptViewBox = function(svg) {
        root.box = svg.getBBox();

        // TODO: why svg is turned upside down?!
        svg.setAttribute('transform', 'scale(1, -1)');

        svg.setAttribute('viewBox', root.box.x+' '+root.box.y+' '+root.box.width+' '+root.box.height);
    };

    /*
     * Pass options when class instantiated
     */
    this.construct(options);

};

Как я уже упоминал, я вообще не силен в js, поэтому буду признателен любой критике и советам. Именно так мы становимся мудрее.
Как вы можете видеть, в методе SvgMap.createToolTipContext() формируется текст для всплывающих подсказок. Плюс есть SvgMap.mouseClick(), где происходит обработка клика.
Мне бы хотелось, чтобы пользователи виджета могли переопределять эти методы в своем коде. Можно выводить любые данные из svg (например добавить поле в каждый path "itemsCount"). Ну а обработчик клика я вообще не могу захардкодить.
Вопрос - как в js перегружать методы класса? Могу предположить, что эти методы можно передать как параметр при созднии объекта.

2. Как пользоваться тегами в git? Я добавил два тега v0.0.1 и v0.0.2 Появилось два релиза, но это как-то слабо смахивает на "релиз" ) В целом я не понимаю их надобность в таком вот виде. Переключаться между ветками/коммитами я и через tig могу (даже с большим удобством). Пакаджист почему-то вообще не показывает эти теги. В общем, непонял я этот инструмент. Расскажите.

3. Обработка ошибок в js.

Код: Выделить всё

        ['id','type','data'].forEach(function (param) {
            if(typeof options[param] === 'undefined') {
                throw new Error(param + ' parameter is missed');
            }
        });

Как я понимаю, нужно писать единый обработчик на уровне класса? Или на уровне фреймворка (jQuery)? В проекте может использоватья несколько различных библиотек. В таком случае где единый центр обработки исключений? Или у каждой библиотеке свой должен быть? Тоже не понимаю таких тонкостей, прошу дать комментарии.

4. Пытаюсь установить свой виджет через composer в пустую дирректорию (только composer.json):

Код: Выделить всё

ghopper@test:~/delme$ composer install
Loading composer repositories with package information
Updating dependencies (including require-dev)
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - The requested package ghopper/svg-map * is satisfiable by ghopper/svg-map[dev-master] but these conflict with your requirements or minimum-stability.

Сам composer.json:

Код: Выделить всё

{
    "require": {
        "ghopper/svg-map": "*"
    }
}

Это что от меня хотят?

[ElisDN]

2,4. Ругается на то, что не находит релизов в Packagist. После загрузки тега на GitHub нажмите кнопку Update в Packagist или настройте хук для автообновления.

[Dominus]

2. Когда вы готовы сделать релиз, просто возьмите нужный мерж-коммит и повесьте на него тег.

Код: Выделить всё

git tag -a v1.0.0 -m "Version 1.0.0"

Чтобы запушить теги на удалённый сервер

Код: Выделить всё

git push --follow-tags

Параметр --follow-tags нужен для того, чтобы запушить только аннотированные теги и не пушить легковесные (lightweight), если они у вас вдруг есть.

https://git-scm.com/book/ru/v2/%D0%9E%D ... 0%BC%D0%B8

[GHopper]

У нас уже есть результат! Виджет, позволяющий "на лету" создавать svg и подключать к нему собственные обработчики событий.

Пример использования:
берем изображение автомобиля, конвертируем в svg и группируем path по нужному критерию. Пишем нужные js-обработчики. Передаем все полученное в виджет и у нас на странице интерактивное изображение автомобиля, на котором можно кликать в колесо/зеркало/копот/антенну и т.п. Думаю многим это будет полезно.
В демо есть данные для построения карты России. Можно прикрутить на любой сайт для выбора региона доставки или отображения информации по филиалам.

В общем, как я счита, область применения данного виджета широкая и я бы хотел его как-то популяризировать. Хочу ветки, форки, пул.реквесты и пр. прелести командной работы. Где размещаться? Как привлечь контрибов?

Могу предположить, что перевод на английский и добавление новых примеров поспособствует развитию виджета. Еще какие предложения есть?

Или все тлен? Набросал я за пару дней корявый виджет, который "никому не нужОн аще", написан бездарно и форкать его смысла нет, т.к. проще скачать и самому дописать нужный функционал?

Дайте обратную связь. Где самый простой путь ступить на пусть open source?

[rugabarbo]

Где самый простой путь ступить на пусть open source?

Прежде, чем начать командовать, научись подчиняться (Солон Афинский).

[GHopper]

А как в yii2 виджете пользовать иконки из fontawesome? Как я понимаю, он интегрирован во фреймворк? Нужно просто assets настроить правильно?

И еще вопрос - packagist.org какую ветку скачивает? Дефолтную или всегда master? Я же могу иметь ветку master и в нее вмерживать все фичи, разрабатываемые в других ветках. Таким образом в packagist.org всегда будет только завершенные фичи, а на github весь проект со всеми наработками. Правильно я понимаю логику работы?

[ElisDN]

1. В composer.json require добавить любой чужой yii2-fontawesome и в вставить его FontAwesomeAsset к своему в $depends.

2. Не заморачивайтесь. Packagist собирает завершённые теги из всего проекта.

[Dominus]

А как в yii2 виджете пользовать иконки из fontawesome? Как я понимаю, он интегрирован во фреймворк? Нужно просто assets настроить правильно?

Если вы про встраивание в свой виджет то можно вот так:
1. https://github.com/Dominus77/yii2-fonta ... r.json#L15
2. https://github.com/Dominus77/yii2-fonta ... eAsset.php
3. https://github.com/Dominus77/yii2-fonta ... et.php#L30