Hi, my name is Maribeth and in this talk I'm going to discuss
how to build a Blockly plugin. There are four steps to building a Blockly plugin
and in this talk I'll discuss each of them and point you to resources for more information.
The four steps are Suggestion, Discussion, Implementation, and Publishing.
The first thing to know is that there are two kinds of plugins: first party and third party.
First party plugins are maintained by the Blockly team and published under the Blockly scope.
Third party plugins are any others. We do accept contributions from the community for first party
plugins but they have to meet some requirements. They should be general purpose, stable, and easy
to use. We also ask that the author be willing to handle maintenance and bugs with the plugin.
If you want to create a third party plugin, go for it! The Blockly team doesn't publish these
so it's up to you how to create and maintain your plugin. Others may be interested in your
plugin as well so you should still consider publishing it. But the first two steps here,
Suggestion and Discussion, won't apply to you. If you want to create a first party plugin,
the first step is to file a feature request on github. You should explain your idea thoroughly,
possibly provide screenshots or examples, and explain why it should be a first party plugin.
On your github issue, the Blockly team will discuss with you the plan for your plugin. This
is the second step. This may include the proposed API, any changes necessary in Blockly core to
support it, plans for testing, and a name for the plugin. During this phase we may decide your
plugin is a better fit as a third party plugin and close the issue. You should still implement your
plugin if that happens, we just won't be able to maintain it as a first party Blocky plugin.
After the plugin has been approved or whenever you're ready to start working on a third-party
plugin, it's time for implementation work. We've created a handy script in our dev tools
called create-package that bootstraps your plugin and creates the skeleton files you'll need.
You can execute the script through npm with "npx @blockly/create-package" and then the plugin name.
Note that we have naming requirements so fields should start with "fields" such as "field-slider";
"themes" start with "theme"; and so on. In my example shown here I created a plugin
called "summit-example". Let's look at the files it creates for you. There's one called
GETSTARTED that tells you the scripts available. We'll look at those later.
There's also src and test directories. The source directory is where you'll implement
the logic for your plugin. What exactly you need to put here is totally up to you.
If you are adding a field then you would create your field definition here. If you are creating
a toolbox, your toolbox and fly-out classes would go here. If you are creating custom scroll logic,
that logic would live here. Since there are so many things you could be doing with a plugin
it's hard to give concrete advice about what exactly goes here, but in general it will be
the implementation logic for the plugin. You can browse the existing plugins for inspiration
or ask on the forum if you're stuck. Note that the index.js file that is automatically created
is the entry point to the code. You can add other files, you just may need to export
them in index.js to make them available after the build step which we'll talk about later.
The other directory created by the script is the test directory. This contains a test page with an
advanced playground automatically configured. In index.js you should set up your plugin to show how
it works. For example if you've created a new field you can create a block using that field
and put one in the toolbox. If you created a toolbox you would configure the playground to
use that toolbox. Or if you created some other plugin that needed to be toggled off and on,
you would do that logic here. The goal of this is to provide a demo of your plugin and a quick
way to see it in action. You can run "npm run start" to automatically build your plugin,
start a server, and open your test page. This script is part of Blockly's dev scripts and it
was automatically configured when you ran the create-package script. You can also run "npm
run build" to execute just the build steps and make sure you don't have any compilation errors.
And "npm run lint" to run the linter to ensure you followed the style guide.
Those scripts are all listed in the GET STARTED page that was created for you as well.
You should also add unit tests to your plugin in the test directory.
During the discussion phase you may have already created a testing plan which you can follow. You
should add unit tests to increase confidence that your plugin behaves as expected and so that we
can catch problems introduced by future changes. For more information about testing you can watch
Monica's talk about mocha. "npm run test" will run any mocha test present in your plugin directory.
The creation script also creates a package.json and a README. The README
should contain information about your plugin and instructions on how to use it. In the package.json
you should update the metadata about the plugin so that other developers can find the package on npm,
and you'll have to list any dependencies of your project. Blockly is generally listed as a peer
dependency of plugins because we expect people using plugins to already have the Blockly package
installed. You should make sure that the version of Blockly listed here matches what is actually
needed by the plugin. For example if you're using an API in core Blockly that was just published
in the most recent release, that's the version that should be listed here as a peer dependency.
While the plugin is under development it will be marked private in the package.json.
This will prevent it from being published which is the next step in creating a plugin.
When the plugin is ready to be launched, you'll remove the private key from the package.json.
Then it will be automatically published to npm by the Blockly
team when we release Blockly Samples. This typically happens once a week on Thursdays.
If you created a third party plugin, publishing it on npm is optional but you'll have to publish
it yourself if you choose to. For first party plugins, we maintain a plugin showcase
on the github pages of Blockly Samples, so you should also add it to that page.
Those are the steps! So if you're ready to build a plugin now you can check out
the feature request proposals on Blockly Samples or you can propose your own idea.
If you're ready to build a plugin now, you can check out the feature request proposals
on Blockly samples or you can propose your own idea for a plugin.