LogoLogo
HomeAPIBlog
3.0.0-SNAPSHOT
3.0.0-SNAPSHOT
  • INTRODUCTION
    • Getting Started
      • Running Local Development Servers
      • Beginner Tutorial: Hello World
      • Beginner Tutorial: Hello Database
      • Tutorial: Wheels, AJAX, and You
    • Frameworks and Wheels
    • Requirements
    • Manual Installation
    • Upgrading
    • Screencasts
  • Command Line Tools
    • CLI Commands
    • wheels - commands
    • wheels generate - commands
    • wheels dbmigrate - commands
    • wheels plugins - commands
  • Working with Wheels
    • Conventions
    • Configuration and Defaults
    • Directory Structure
    • Switching Environments
    • Testing Your Application
    • Contributing to Wheels
    • Documenting your Code
  • Handling Requests with Controllers
    • Request Handling
    • Rendering Content
    • Redirecting Users
    • Sending Files
    • Sending Email
    • Responding with Multiple Formats
    • Using the Flash
    • Using Filters
    • Verification
    • Event Handlers
    • Routing
    • URL Rewriting
      • Apache
      • IIS
      • Tomcat
      • Nginx
    • Obfuscating URLs
    • Caching
    • Nesting Controllers
    • CORS Requests
  • Displaying Views to Users
    • Pages
    • Partials
    • Linking Pages
    • Layouts
    • Form Helpers and Showing Errors
    • Displaying Links for Pagination
    • Date, Media, and Text Helpers
    • Creating Custom View Helpers
    • Localization
  • Database Interaction Through Models
    • Object Relational Mapping
    • Creating Records
    • Reading Records
    • Updating Records
    • Deleting Records
    • Column Statistics
    • Dynamic Finders
    • Getting Paginated Data
    • Associations
    • Nested Properties
    • Object Validation
    • Object Callbacks
    • Calculated Properties
    • Transactions
    • Dirty Records
    • Soft Delete
    • Automatic Time Stamps
    • Database Migrations
      • Migrations in Production
    • Using Multiple Data Sources
  • Plugins
    • Installing and Using Plugins
    • Developing Plugins
    • Publishing Plugins
  • Project Documentation
    • Overview
  • External Links
    • Source Code
    • Issue Tracker
    • Sponsor Us
    • Community
Powered by GitBook
LogoLogo
On this page
  • Requirements
  • Setup a forgebox user account
  • Ensure you've got a box.json in your plugin root
  • Ensure you've set some critical box.json attributes
  • Using the forgebox staging server (optional)
  • Publishing a plugin to forgebox
  • Adding a new version via publishing scripts
  • Removing a plugin from forgebox

Was this helpful?

Edit on GitHub
Export as PDF
  1. Plugins

Publishing Plugins

How to publish your plugin to forgebox.io via CommandBox

PreviousDeveloping PluginsNextOverview

Last updated 21 days ago

Was this helpful?

So, you've created your new magic, world solving plugin, and naturally, you want to share it with the world. Wheels uses as a plugins repository. This enables us to manage our Wheels application's dependencies, install updates easily via CommandBox and more.

As a plugin author, it's well worth spending a little time setting yourself up to work with forgebox with the minimum amount of effort. Once done, you'll be able to either publish directly from the commandline, or upload to forgebox manually.

This tutorial makes extensive use of CommandBox, GIT and the Wheels CLI.

Requirements

We strongly recommend always having the latest version of .

You'll also want the Wheels CLI. You can install that in CommandBox via install wheels-cli. This will also update it if you've got an older version installed.

Some scripted commands also require the git CLI, although these are technically optional.

Setup a forgebox user account

If you've not got a account you can either or very quickly via CommandBox itself

CommandBox
# Register for an account
$ forgebox register

Once you've got your credentials, you should be good to go.

If you've already got an account, you need to login at least once, which will store an API token for future use:

CommandBox
# Login
$ forgebox login

# (optional) Check which account you're logged in with
$ forgebox whoami

Ensure you've got a box.json in your plugin root

Forgebox uses your local box.json - you'll need one! Critical package information like the name of your plugin and the location are stored here. You can create one manually, or you can run:

Shell
# Create a basic box.json
$ init

# Or pass in parameters at the same time
$ init name="My Funky Plugin" slug=my-funky-plugin version=1.0.0 type="wheels-plugins"

# Or use the wizard
$ init --wizard

Ensure you've set some critical box.json attributes

In order for other Wheels users to quickly identify and install your plugin via the Wheels CLI, make sure you set the following box.json attributes - whilst a standard box.json might only have name, version,author, we need a little more information. Here's a template to get you started: (replace the values in CAPS)

box.json
{
  // Required:
 "name":"PLUGIN-NAME",
 "version":"0.0.1",
 "author":"YOURNAME",
  // Required: GitHub Repository stub
 "location":"GITHUBUSERNAME/GITHUB-REPONAME#v0.0.1",
  // Required: Should always be /app/plugins/
 "directory":"/app/plugins/",
  // Required: Should always be true
 "createPackageDirectory":true,
  // Required: Must be the name of your primary CFC File
 "packageDirectory":"PLUGIN-NAME",
  // Required: The Forgebox slug, must be unique
 "slug":"FORGEBOX-SLUG",
  // Required: Must be wheels-plugins
 "type":"wheels-plugins",
  // Required: From here is optional but recommended
 "homepage":"https://github.com/GITHUBUSERNAME/GITHUB-REPONAME",
 "shortDescription":"PLUGIN DESCRIPTION",
 "keywords":"KEYWORD",
 "private":false,
 "scripts":{
   "postVersion":"package set location='GITHUBUSERNAME/GITHUB-REPONAME#v`package version`'",
 "patch-release":"bump --patch",
 "minor-release":"bump --minor",
 "major-release":"bump --major",
 "postPublish":"!git push --follow-tags && publish"
  }
}

Your completed box.json might look something like this:

box.json
{
  // Required:
 "name":"Shortcodes",
 "version":"0.0.4",
 "author":"Tom King",
  // Required: GitHub Repository stub, including version hash
 "location":"neokoenig/wheels-shortcodes#v0.0.4",
  // Required: Should always be /app/plugins/
 "directory":"/app/plugins/",
  // Required: Should always be true
 "createPackageDirectory":true,
  // Required: Must be the name of your primary CFC File
 "packageDirectory":"Shortcodes",
  // Required: The Forgebox slug, must be unique
 "slug":"shortcodes",
  // Required: Must be wheels-plugins
 "type":"wheels-plugins",
  // Required: From here is optional but recommended
 "homepage":"https://github.com/neokoenig/wheels-shortcodes",
 "shortDescription":"Shortcodes Plugin for Wheels",
 "keywords":"shortcodes",
 "private":false,
 "scripts":{
   "postVersion":"package set location='neokoenig/wheels-shortcodes#v`package version`'",
 "patch-release":"bump --patch",
 "minor-release":"bump --minor",
 "major-release":"bump --major",
 "postPublish":"!git push --follow-tags && publish"
  }
}

Using the forgebox staging server (optional)

CommandBox
# Add staging server configuration
$ config set endpoints.forgebox.APIURL=http://forgebox.stg.ortussolutions.com/api/v1

# Revert back to production configuration
$ config clear endpoints.forgebox.APIURL

Remember this configuration will "stick", so make sure you change it back afterwards. (I find once changed, it might not kick in until you reload the CommandBox shell via r).

Publishing a plugin to forgebox

Both Wheels CLI and Forgebox are expecting a tagged release with the plugin contents (e.g. zip). So the best way to publish is to...

  1. Navigate into the plugin directory

  2. Ensure that directory is authorized to publish the repo (e.g. git remote -v should list your fetch/push endpoints)

Note: Git dislikes nested repos, so it's best to setup a test wheels site specifically for plugin development/deployment. Then git init within each plugin directory itself, but not at the root. (e.g. /app/plugins/PluginName/)

CommandBox
# from CommandBox prompt, within plugin directory
$ run-script patch-release

ForgeBox does not store your actual package files like npm, but points to your download location.

The following should happen (again, assuming you have git publish rights from that plugin directory)

  1. Auto increment your version number within box.json

  2. Push updated box.json to forgebox (with new version number + location)

  3. Create a git "Tagged Release" which is basically a zip containing the source files

Once you run this command, you can run forgebox show my-package to confirm it's there. If you change the slug, a new package will be created. If you change the version, a new version will be added to the existing package.

Adding a new version via publishing scripts

By adding the following block to our box.json, we can more easily deploy new versions with a single command:

box.json
"scripts":{
   "postVersion":"package set location='GITHUBUSERNAME/GITHUB-REPONAME#v`package version`'",
 "patch-release":"bump --patch",
 "minor-release":"bump --minor",
 "major-release":"bump --major",
 "postPublish":"!git push --follow-tags && publish"
  }

Obviously, you'll need to change location='GITHUBUSERNAME/GITHUB-REPONAME#v to your repo.

With these in place, once you've committed your changes to your local repository, you can now do:

CommandBox
# Don't forget to commit your changes. You can access git directly from commandbox using !
$ !git add .
$ !git commit -m "my new changes"

# Move from 1.0.0 -> 1.0.1
$ run-script patch-release

# Move from 1.0.0 -> 1.1.0
$ run-script minor-release

# Move from 1.0.0 -> 2.0.0
$ run-script major-release

This will:

  • Set the package location to include the new version number

  • Publish to forgebox.io

  • Push your changes to gitHub (assuming you've set that up)

  • Publish a gitHub tagged release

This saves you having to manually update the version number too!

Commandbox
# Example output of a patch release
$ run-script patch-release

Running package script [patch-release].
> bump --patch && publish
Set version = 0.1.7

Running package script [postVersion].
> package set location='neokoenig/wheels-cli#v`package version`'
Set location = neokoenig/wheels-cli#v0.1.7
Package is a Git repo.  Tagging...
Tag [v0.1.7] created.
Sending package information to ForgeBox, please wait...
Package is alive, you can visit it here: https://www.forgebox.io/view/wheels-cli

Running package script [postPublish].
> !git push --follow-tags
Counting objects: 10, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (10/10), 908 bytes | 0 bytes/s, done.
Total 10 (delta 5), reused 0 (delta 0)
remote: Resolving deltas: 100% (5/5), completed with 4 local objects.
To https://github.com/neokoenig/wheels-cli.git
   477648f..400604b  master -> master
 * [new tag]         v0.1.7 -> v0.1.7

Package published successfully in [forgebox]

Lastly, you can double check it's made it into the plugins list via wheels plugins list

Removing a plugin from forgebox

Likewise, you can unpublish a plugin, but keep in mind people might be relying on your plugin, so don't do this lightly!

CommandBox
// Remove all versions of a package
$ unpublish

// Remove a specific version of a package
$ unpublish 1.2.3

// Skip the user confirmation prompt
$ unpublish 1.2.3 --force

If this is the first time you've done this, you might want to try the forgebox staging server. That way you can make sure your publishing process is spot on without having lots of unnecessary versions pushed up. You can view the staging server version at

forgebox.io
CommandBox
forgebox.io
register directly on forgebox
http://forgebox.stg.ortussolutions.com/