getgrav/grav-plugin-devtools

Grav Devtools Plugin

Grav Devtools Plugin

The devtools is a Grav Plugin that lets you quickly create a scaffolding for your new plugins and themes. The plugin provides CLI commands that allow for the quick and easy deployment of a sample scaffolding for your new plugin.

Installation

GPM Installation (Preferred)

The simplest way to install this plugin is via the Grav Package Manager (GPM). From the root of your Grav install type:

bin/gpm install devtools

Manual Installation

If for some reason you can't use GPM you can manually install this plugin. Download the zip version of this repository and unzip it under /your/site/grav/user/plugins. Then, rename the folder to devtools.

You should now have all the plugin files under

/your/site/grav/user/plugins/devtools

Configuration

By default, devtools will perform a check with the online gpm repository to ensure name-collision avoidance. If you wish to not perform this online check, change the devtools.yaml at user/config/plugins from collision_check: true to collision_check: false.

Usage

Plugin Scaffolding

To create a new plugin you simply need to run: bin/plugin devtools new-plugin and fill in the few questions at the prompts:

> bin/plugin devtools new-plugin
Enter Plugin Name: MyPlugin
Enter Plugin Description: My New Custom Plugin
Enter Developer Name: Johnny Rotten
Enter GitHub ID (can be blank): pretty-vacant
Enter Developer Email: [email protected]

SUCCESS plugin myplugin -> Created Successfully

Path: /home/johnnyr/webroot/grav-installation/user/plugins/myplugin

Theme Scaffolding

To create a new theme you simply need to run: bin/plugin devtools new-theme and fill in the few questions at the prompts:

> bin/plugin devtools new-theme
Enter Theme Name: MyTheme
Enter Theme Description: My New Custom Theme
Enter Developer Name: Johnny Rotten
Enter GitHub ID (can be blank): pretty-vacant
Enter Developer Email: [email protected]
Please choose a template type
  [pure-blank ] Basic Theme using Pure.css
  [inheritance] Inherit from another theme
  [copy       ] Copy another theme
 > pure-blank

SUCCESS theme mytheme -> Created Successfully

Path: /home/johnnyr/webroot/grav-installation/user/themes/mytheme

There are three template creation options

1. pure-blank - This is a very basic blank theme that uses the Pure CSS framework
2. inheritance - This creates a very basic template with minimal files that inherits a base theme. To find out more about theme inheritance, check out the subject in more details on the Grav Learn site.
3. copy - This allows you to create a new theme based on an existing theme. This is the simplest way to get started with a new theme by using another theme as the basis.

Skipping Online Project Name Collision Checking

By default, devtools will check your project's name with the existing gpm ecosystem to ensure no collisions. In order to skip this check, add an --offline or -o to your command:

`bin/plugin devtools new-theme --offline`

or

`bin/plugin devtools new-theme -o`

grav-plugin-devtools's Issues

Output cmd does not correctly show colours: <yellow>Plugin Name</yellow>

$ bin/plugin devtools newplugin
Enter <yellow>Plugin Name</yellow>: test
Enter <yellow>Plugin Description</yellow>: test
Enter <yellow>Developer Name</yellow>: test
Enter <yellow>GitHub ID</yellow> (can be blank):
etc

What is autoload?

When creating a new plugin, the devtools page uses a template that contains an autoload function. However this function fails, as the included folder does not exist by default. That confuses me.

I guess it makes most sense to:

• Remove this function
• Add the missing folder
• Or explain it inside the generated classes AND the tutorial

An autogenerated template that fails from the beginning is not a good start for new plugin devs.

"New" is a reserved keyword

"New" is a reserved keyword in PHP and it is not the only one.

When running command:

$ sudo bin/plugin devtools newtheme
Enter Theme Name: new
Enter Theme Description: asd
Enter Developer Name: John Doe
Enter Developer Email: [email protected]
Please choose a template type
  [0] pure-blank
  [1] inheritance
> 0

SUCCESS theme new -> Created Successfully

Path: /var/www/grav-admin/user/themes/new

The error arises after you set the theme active and reload the blog (admin-side not affected).

ParseError syntax error, unexpected 'New' (T_NEW), expecting identifier (T_STRING)

This is caused because the theme's name is "new" and devtools automagically creates all files necessary.

Within the user/themes/new folder there will be a new.php that contains the line

class New extends Theme 

As said in php.net.

You cannot use any of the following words as constants, class names, function or method names. Using them as variable names is generally OK, but could lead to confusion.

As of PHP 7.0.0 these keywords are allowed as property, constant, and method names of classes, interfaces and traits, except that class may not be used as constant name.

---

There should be some sort of prevention when using any of the keywords listed at php.net.

Broken Composer autoload.php reference

To Reproduce

After using bin/plugin devtools new-plugin and filling out the form, a new plugin is generated in the expected location. I attempt to view the site at http://siteURL.tld, but am greeted with a PHP error:

Whoops \ Exception \ ErrorException (E_COMPILE_ERROR)
Grav\Plugin\WpImporterPlugin::autoload(): Failed opening required '/var/www/html/user/plugins/wp-importer/vendor/autoload.php' (include_path='.:/usr/share/php')

Expected Result:

An empty plugin is present in user/plugins, and the site continues to function.

Observed Result:

The plugin is created, but it expects a non-existent autoload to be present at vendor/autoload.php.

Workaround:

I'm able to comment out line 27 of my new plugin to restore site functionality
//['autoload', 100000], // TODO: Remove when plugin requires Grav >=1.7
Alternatively, if my plugin has some composer dependencies, I could install those.

new-theme assumes I'll be publishing the theme on GitHub

Homepage, bugs, and readme are all set to a GitHub URL based on... my real name.

Reference to missing file in base.html.twig from pure-blank theme

In the default generated pure-blank theme there is a reference to partials/metadata.html.twig in the head code.

grav-plugin-devtools/components/theme/pure-blank/templates/partials/base.html.twig

Line 11 in e702cd8

{% include 'partials/metadata.html.twig' %}

This file doesn't exist in the partials directory and no error is raised on the page. This file should be created.

Tailwind theme created by devtools plugin is broken?

Hi there,

I play around with Grav CMS and its plugin dev tools. With this plugin I had successfully created a theme with tailwind.

I am a bit confused about a thing with this theme. In the “head” of the page I can see this code:
<link rel="icon" type="image/png" href="/user/themes/taily/images/logo.png" />

I can click on the link and I see the Grav-logo in a new browser window.

But I can not see this image on the page itself. Why?

The code in base.html.twig of the image is this:
<link rel="icon" type="image/png" href="{{ url('theme://images/logo.png')|e }}" />

Also the whole page output seems not working right now. It seems that the stylesheet is not loading exactly!

Is the theme broken? Please fix it, I wanna use it for Grav CMS!

ELK issues and help.

Hello Gary and Kapil,

Hope you guys had a fun weekend. When I try to run the following command, I keep getting 'bin is not recognized as an internal or external command'. Any help regarding handling this error would be appreciated.

bin/logstash -f logstash-simple.conf

Thank you.

new scss folder

as a feature, besides the new css folder, ther could be an option to create a scss/sass folder with a custom.scss / sass file that can be complied to the already existing custom.css in the css folder ?

Clarify user should cd into folder of plugin before running 'composer update'

After creating a new plugin, devtools notes: "Make sure to run composer update to initialize the autoloader".

This is probably confusing to users not familiar with composer and could be formulated more clearly. Since devtools already knows the name of the new plugin, it could be:

Make sure to $ cd user/plugins/<plugin name> into the folder of the new plugin and run $ composer update to initialize the autoloader

error when creating new theme

When you create a new theme, an error is displayed:

`...Please choose a template type
[0] pure-blank
[1] inheritence

PHP Notice: Undefined variable: output in /var/www/.../vendor/symfony/console/Helper/QuestionHelper.php on line 449
PHP Notice: Undefined variable: exitcode in /var/www/.../vendor/symfony/console/Helper/QuestionHelper.php on line 449
PHP Warning: exec() has been disabled for security reasons in /var/www/.../vendor/symfony/console/Helper/QuestionHelper.php on line 449
PHP Notice: Undefined variable: exitcode in /var/www/.../vendor/symfony/console/Helper/QuestionHelper.php on line 451...`

But the theme is created, nothing unusual. What could be the problem?
Thanks

Declaration of theme_config removed in base.html.twig, but not in navigation.html.twig

In theme pure-blank, the definition of theme_config has been removed at line 1 of base.html.twig, but is still used in navigation.html.twig:

line 26: {% if theme_config.dropdown.enabled %}

Either re-define theme_config, or change navigation.html.twig to use config.theme or theme to access its properies.

new-theme fails with invalid argument exception

I just tried creating a new theme as per the https://learn.getgrav.org/themes/theme-tutorial

After entering all the information when prompted
I get the following exception

 [InvalidArgumentException]                 
 Identifier "flex-entries" is not defined.

This occurs irrespective of choosing "pure-blank" or "inheritence" option

Update pure to https CDN

Very small thing, but... latest Pure release https://unpkg.com/[email protected]/build/pure-min.css (please note HTTPS)

error "Cannot copy non-existing folder" while creating inherited theme

grav-plugin-devtools/cli/NewThemeCommand.php

Line 128 in 81ffcab

array('pure-blank' => 'Basic Theme using Pure.css', 'inheritance' => 'Inherit from another theme', 'copy' => 'Copy another theme')

pb inheritance vs inheritence: 
According to my dictionary "inheritance" is correct. so I guess the directory components/theme/inheritence/ should be components/theme/inheritance/ instead. At least that how I manage to make it works.

Creating new-plugin: config.platform.php: 7.1.3 prevents installing packages requiring php 8.*

When creating a new 'blank' plugin using devtools the following config section in composer.json, prevents installing packages that require php 8.*

"config": {
  "platform": {
    "php": "7.1.3"
  }
}

PHP fatal creating new plugin with Shortcode UI enabled

Whenever I use bin/plugin devtools new-plugin with the Shortcode UI plugin enabled, I get this error:
PHP Fatal error: Uncaught Error: Class 'Grav\Plugin\ShortcodeUi\ShortcodeUiTwigExtension' not found in /var/www/html/user/plugins/shortcode-ui/shortcode-ui.php:45
The workaround is to disable Shortcode UI plugin temporarily.

`readme` vs `docs`

In the scaffolding the new-plugin command creates, the blueprints.yaml file has a readme field but the plugin system actually pulls from the docs field. Is this a problem with how the plugin page is displaying things (e.g., I couldn't find readme or docs in the sample plugin blueprints)? Or should the plugin change the boilerplate? Thanks!

[Suggestion| Feature request] Add the ability to generate a blueprint file from the command line

Hi,

I thought it would be a nice addition to allow the user to generate some grav-specific files frome the command line.

Most of the time, I copy paste these blueprints as I can not remember it or because these files are very indentation-sensitive.

Here are some files I have to write on almost all my projects and that could be useful in my opinion:

New tab in blueprint

title: Item
'@extends':
    type: default
    context: blueprints://pages

form:
  fields:
    tabs:
      fields:
        blog:
          type: tab
          title: MYNEWTAB
          
          fields:
            header.mytextfield:

Append content to the first Tab

title: Gallery
'@extends':
    type: default
    context: blueprints://pages

form:
  fields:
    tabs:
      type: tabs
      active: 1

      fields:
        content:
          fields:
            header.an_example_text_field:
              type: text
              label: Add a number
              default: 5
              validate:
                required: true
                type: int

Prepend content to the first tab

title: Image Accueil
'@extends':
    type: default
    context: blueprints://pages

form:
  fields:
    tabs:
      type: tabs
      active: 1

      fields:
        content:
          fields:
            header.an_example_text_field:
              ordering@: 0
              type: text
              label: Add a number
              default: 5
              validate:
                required: true
                type: int

Modular pages:

{% extends 'partials/base.html.twig' %}
{% block content %}
{{ page.content }}
    {% for module in page.collection() %}
        {{ module.content }}
    {% endfor %}
{% endblock %}

There might be some other useful files.
Let me know your thoughts!

'bin' is not recognized on windows

I tried the command bin/plugin devtools new-theme and I get this error :
'bin' is not recognized as an internal or external command,
operable program or batch file.

How is this supposed to work on windows?

Thanks!

"Typhoon CustomizedCustomized" bug

Just noticed what appears to be a minor bug. When copying the Typhoon theme to "Typhoon customized", the backend strangely calls it "Typhoon CustomizedCustomized" – see screenshot.

Here's the output from the terminal where I entered "customized" only once:

$ bin/plugin devtools new-theme

Enter Theme Name:
Typhoon customized

github names with capitals in them get - added in them

github usernames in urls are case-insensitive, but when you enter them with capitals in the new-plugin command they get lowercased and - gets added

so AEnterprise becomes a-enterprise

Theme inheritance. Problem with apostrophe and quotes.

Tried to inherit Typhoon theme and got an error:

TypeError
Argument 1 passed to Mexitek\PHPColors\Color::__construct() must be of the type string, null given, 
called in /Users/artyom/domains/mydomain/user/plugins/color-tools/color-tools.php on line 65

/**
     * Instantiates the class with a HEX value
     * @param string $hex
     * @throws Exception
     */
    public function __construct(string $hex). <---- this line
    {
        $color = self::sanitizeHex($hex);
        $this->_hex = $color;
        $this->_hsl = self::hexToHsl($color);
        $this->_rgb = self::hexToRgb($color);
    }

Console:

➜  mydomain bin/plugin devtools new-theme

 Enter Theme Name:
 > My Typhoon

 Enter Theme Description:
 > Customizing Typhoon

 Enter Developer Name:
 > Artyom Mezin

 Enter GitHub ID (can be blank):
 > 7556290

 Enter Developer Email:
 > [email protected]

 Please choose an option:
  [pure-blank ] Basic Theme using Pure.css
  [tailwind   ] Basic Theme using tailwind.css
  [inheritance] Inherit from another theme
  [copy       ] Copy another theme
 > inheritance

 Please choose a theme to extend:
  [0] quark
  [1] typhoon
 > 1


SUCCESS theme My Typhoon -> Created Successfully

Path: /Users/artyom/domains/mydomain/user/themes/my-typhoon

Ok. Cache cleared, browser refreshed, error still exist... found another issue: getgrav/grav#3549

Decided to compare typhoon.yaml and my-typhoon.yaml to find differences and that's it:

Normal typhoon.yaml color block:

colors:                                                             # Doesn't work for modular as the CSS is page-level
  text_style: 'text-gray-600 dark:text-gray-400'                    # Text color (Any valid Tailwind color)
  brightness_lighter: '20'                                          # The percentage amount brighter for *-primary-lighter colors
  brightness_darker: '20'                                           # The percentage amount darker for *-primary-darker colors
  primary: '#3893F8'                                                # The primary accent color used throughout the page (Any valid Tailwind color)

Bad my-typhoon.yaml color block:

colors:                                                             # Doesn't work for modular as the CSS is page-level
  text_style: 'text-gray-600 dark:text-gray-400'                    # Text color (Any valid Tailwind color)
  brightness_lighter: '20'                                          # The percentage amount brighter for *-primary-lighter colors
  brightness_darker: '20'                                           # The percentage amount darker for *-primary-darker colors
  primary: '#3893F8'                                                # The primary accent color used throughout the page (Any valid Tailwind color)

Why does it use ' istead of '?

Same about quotes:

" istead of "

inherited theme is after new theme

when using the cmd line to create a new theme with inheritance, the new theme appears before the inherited theme in the new-theme.yaml thus rendering all modifications / css/twig/etc... useless ..

README.md.twig should reference `component.author.githubid`

I believe that this line in README.md.twig:

{% set developer_hyphenated = (component.author.name|hyphenize) %}

should instead be

{% set developer_hyphenated = component.author.githubid %}

Otherwise, it generates an incorrect link for the repository path in the README.

No option accepted

I get to the stage of choosing an option, and no option is accepted.

Please choose an option
  [pure-blank ] Basic Theme using Pure.css
  [inheritence] Inherit from another theme
  [copy       ] Copy another theme
 > inheritance
 Value "inheritance" is invalid 

I tried as many combinations as I could think of and every one gives the same error.

Wrong folder name: components/theme/inheritence/

When creating new theme using inheritance, plugin devtools tries to copy folder components/theme/inheritance/ but folder is actually named components/theme/inheritence/

Typo in phpdoc in generated plugin?

Is *is a typo? If not, what does it mean?

grav-plugin-devtools/components/plugin/blank/plugin.php.twig

Lines 34 to 38 in 3a82bc0

	/**
	* Composer autoload.
	*is
	* @return ClassLoader
	*/

By the way, the indentation of lines 35, 36, 37 are off... Yes, I know, I'm nitpicking...

Default README title when creating a new theme

I crated a new theme with devtools new-theme and the default title in README.md is

ThemeName Plugin

I guess it should say Theme instead. Nothing major just wanted to share :)

pure-blank theme not visible

After installing the devtools and running the command via the CLI to create a new pure-blank theme I run into the following error:

Notice: Undefined index: bpname in C:\xampp\htdocs\kn\user\plugins\devtools\classes\DevToolsCommand.php on line 83

When checking via the Admin dashboard, the theme is simply not visible at all.

This is based on a clean installation of grav-admin-v1.3.4.
These are the steps I have taken to reproduce this error twice:

• Installing the latest updates from the Admin Dashboard
• Installing the DevTools official plugin in my CLI.
• Select pure-blank theme
• Prompt a name with no uppercases or any special characters

After the 2nd attempt with a clean installation I did notice how it prompted:
SUCCESS theme antimatter -> Created Successfully which seems rather confusing as antimatter is present by default.

Downloading and manually installing the 1.5 version of the DevTools plugin solved the issue (for now).

New plugin : Invalid argument supplied for foreach()

Hello,

I created a new plugin via the cli and before I could enter the plugin name, I got this message twice:

Warning: Invalid argument supplied for foreach() in C:\wamp\www\mysite\system\src\Grav\Common\GPM\Remote\AbstractPackageCollection.php on line 55

After I entered all the infos requested for the creation of a new plugin, it created the files, so I'm not sure if something went wrong or not.

Grav and all plugins are up to date.

Unable to upload file to Flex Directory

Trying to create a Flex Directory that includes file attachments. I based this on an existing SimpleStorage directory I have working, with the following changes:

• Class Grav\Framework\Flex\Storage\FolderStorage instead of Grav\Framework\Flex\Storage\SimpleStorage
• Folder user-data://flex-objects/docfiles instead of user-data://flex-objects/docfiles.json

I can edit and create directory items as expected, and they're stored in the configured location, but selecting a file attachment fails every time:

1. Drag file onto dropzone.
2. Image appears briefly.
3. Error shown below is displayed (selected Admin theme doesn't quite handle the text, so I highlighted it).
4. Closing the error message shows an empty dropzone.

The file field is simply:

    docfiles:
      type: file
      label: 'Document files'
      multiple: true
      accept:
        - image/*

No custom templates created yet. The full blueprint appears below. What am I missing?

title: Documentation
description: Documentation Store.
type: flex-objects

# Flex Configuration
config:
  # Administration Configuration
  admin:
    # Admin menu (optional)
    menu:
      list:
        route: '/userdocs'
        title: User Docs
        icon: fa-fa-file-text-o
        # Authorization to collection admin
        authorize: ['admin.docs', 'admin.pages', 'admin.super']
        # Priority -10 .. 10 (highest goes up)
        priority: 2

    # Admin template type / folder
    template: default

    # List view
    list:
      title: name
      fields:
        published:
          field:
            type: toggle
            label: '<i class="fa fa-tv"></i>'
          width: 8
        postdate:
        doctitle:
          link: edit
        productline:
        srmversion:
        publicversion:

    # Edit View
    edit: 
      title:
        template: '{{ object.doctitle ?? ''Doc Title'' }}'

    # Preview View
    preview:
      enabled: false
      route:
        #template: '/plugins/flex-objects/directory:contacts'

    # Data Export
    export:
      enabled: true
      method: 'jsonSerialize'
      formatter:
        class: 'Grav\Framework\File\Formatter\YamlFormatter'
      filename: 'docfiles'

  # Site Configuration
  site:
    templates:
      collection:
        # Lookup for the template layout files for collections of objects
        paths:
          - 'flex/{TYPE}/collection/{LAYOUT}{EXT}'
      object:
        # Lookup for the template layout files for objects
        paths:
          - 'flex/{TYPE}/object/{LAYOUT}{EXT}'
      defaults:
        # Default template {TYPE}; overridden by filename of this blueprint if template folder exists
        type: default
        # Default template {LAYOUT}; can be overridden in render calls (usually Twig in templates)
        layout: default

  # Data Configuration
  data:
    # Object class to be used, allowing custom methods for the object
    object: 'Grav\Framework\Flex\FlexObject'
    # Collection class to be used, allowing custom methods for the collections
    collection: 'Grav\Framework\Flex\FlexCollection'
    # Index class to be used, works as a quick database-like lookup index
    index: 'Grav\Framework\Flex\FlexIndex'
    storage:
      # Storage class, use single file storage (does not support images and assets)
      class: 'Grav\Framework\Flex\Storage\FolderStorage'
      options:
        formatter:
          # File formatter class, in this case the file is stored in JSON
          class: 'Grav\Framework\File\Formatter\JsonFormatter'
        # JSON file where all the objects will be stored
        folder: user-data://flex-objects/docfiles
    search:
      # Search options
      options:
        contains: 1
      # Fields to be searched
      fields:
        - doctitle
        - productline
        - description
        - docfiles                

form:
  validation: loose

  fields:
    published:
      type: toggle
      label: Published
      highlight: 1
      default: 1
      options:
        1: PLUGIN_ADMIN.YES
        0: PLUGIN_ADMIN.NO
      validate:
        type: bool
        required: true

    doctitle:
      type: text
      label: Document title
      validate:
        required: true
    
    postdate:
      type: date
      label: 'Date posted'
      validate:
        required: false

    srmversion:
      type: text
      label: 'SRM Version'
      validate:
        required: true

    publicversion:
      type: text
      label: 'Public Version'
      validate:
        required: true

    draft:
      type: text
      label: 'Draft number'
      validate:
          required: false
  
    productline:
      type: select
      label: Product line
      options:
        trellixlighting: 'Trellix Lighting'
        trellixlocate: 'Trellix Locate'
        trellixcore: 'Trellix Core'
        fifthlight: 'Fifth Light'
        other: 'Other'
    
    description:
      type: textarea
      label: "Full Description"
      validate:
        type: textarea

    docfiles:
      type: file
      label: 'Document files'
      multiple: true
      limit: 0
      accept:
        - image/*

Theme blueprints template missing docs header

Noticed this when building and publishing some themes using devtools. A readme header is generated but not a docs header, which is what the getgrav.org downloads uses for documentation links rather than the former.

We might see more handy theme docs links in the theme download centre if this is added.

PR forthcoming! :)

Object of class Grav\Plugin\DevToolsPlugin could not be converted to string

I need to dump Grav::instance() to find the information I'm looking for. Kint is usually helpful in such a drupal-ish situation. But it's not possible:

require_once('/usr/local/bin//kint.phar');
\Kint::dump(Grav::instance());

Not sure whether or not DevToolsPlugin is the unique plugin that block Kint from dumping Grav::instance()

New Template shows erroneous menu

Still learning but just created a new template and see the site has menu items "Features", "Pricing", "Screenshots", etc. Where do these come from? I don't have any pages with these names and can't find these words anywhere in the template code base. Not only that, but of the two pages I do have saved, only the home pages shows on the front end. Advice?

Allows creating theme with illegal class name. Enabling theme crashes whole instance.

Howdy friends. The CLI will create a theme that has a name starting with a number even though it directly uses that value as a class name. Enabling the theme dumps the whole instance with a parse error.

<?php
namespace Grav\Theme;
 
use Grav\Common\Theme;
 
class 2numeric4grav extends Theme
{
    // Access plugin events in this class
}
 

Arguments

    "syntax error, unexpected integer "2", expecting identifier"

I imagine this is pretty low priority, but also seems like a trivial addition to your existing validation check... but I only skimmed it!

(If anyone lands here investigating how to restore your crashed instance after enabling a theme with an illegal name, just go into the grav's system.yaml and swap out any references to the bad theme name with another valid theme and you'll be good to go.)

Inheritance is misspelled

When creating a new theme, the selection to inherit from an existing theme is misspelled as inheritence instead of inheritance.

new-theme doesn't accept valid TLDs

My email has the gTLD "solutions", which is, apparently, invalid. This isn't the only thing I've used that does that, so I used my usual workaround, pointing to mysite + "solutions.com" (which I also own for this purpose...)

"bin/gpm install devtools" command throws "Permission denied"

Even with the 755 folder access rights.

The reason of it - you should use php bin/gpm install devtools instead of bin/gpm install devtools