README

Charcoal contrib guide is a contrib set to add videos (youtube's, at some point vimeo's) as tutorials in the charcoal-admin interface.

Upon installation, you will get

Installation
- Dependencies
Service Provider
- Parameters
- Services
Configuration
Usage
Development
Credits
License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-guide

Dependencies

Required

PHP 5.6+: PHP 7 is recommended.
charcoal-admin: >=0.15=

PSR

PSR-7: Common interface for HTTP messages. Fulfilled by Slim.
PSR-11: Common interface for dependency containers. Fulfilled by Pimple.

Configuration

In your project's config file, require the notification module :

{
    "modules": {
        "charcoal/admin/guide/guide": {}
    }
}

Then, add an youtube api key: To find an api key, go to https://console.cloud.google.com, reach a billable project then go to credentials, and add an api key. Youtube Data Api must be enabled to restrict key accordingly. To enable the api, go to Library, then search for Youtube Data Api.

{
    "apis": {
        "google": {
            "youtube": {
                "key": "xxxxxxx"
            }
        }
    }
}

Usage

Upon installation, you will get a new item in the system menu Video tutorials which will bring you to a menu for the charcoal admin guide interface. To see the scraper interface and the video association interface, you will need to have superuser access or gain access to charcoal/admin/guide/edit. Without the proper access, you will only be able to see the videos list.

Scraping youtube videos

Go to admin/guide/scrape-video, type in the playlist ID and press Import. You be redirected to the admin/guide/video page with all the newly imported videos, or none if the playlist was not accessible for any reason. Importing videos WILL overwrite existing videos, you cannot import multiple youtube playlist. Importing videos will remove all attached videos that were previously defined in the admin/guide/associate-video page.

Associating videos

As of version 0.1.0, you can associate a video to either a form or a table (widget). Meaning you can only associate videos to objects, not templates. The object list comes from the admin menu.

To associate a video, choose a Widget, then a property when defined (mostly template_ident), then, of course, the actual video. Not defining any property will results as a default behavior, thus applying the video to all entries from the choosen object. You can then press save in the sidebar and that's it. Javascript interpreter will define if a form or a table has a video attached to it.

Important notes

The order in which you define the videos has an impact on the displayed video, as only one video can be assigned to an object entry. For example, if you choose to assign a video to a form without defining the property, all subsequent videos will be avoided.

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

Development Dependencies

[php-coveralls/php-coveralls][phpcov]
[phpunit/phpunit][phpunit]
[squizlabs/php_codesniffer][phpcs]

To do list

Add support for vimeo
Add support for custom video URL
Add support for adding videos without overwriting it all
Add support for templates as opposed to widgets

Coding Style

The charcoal-contrib-guide module follows the Charcoal coding-style:

PSR-1
PSR-2
PSR-4, autoloading is therefore provided by Composer.
phpDocumentor comments.
phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.

locomotivemtl / charcoal-contrib-guide

Maintainers

Details