How to Add a Plugin

MooForge is tightly integrated with GitHub. All the plugins data is stored there, even the downloads. In order to add your plugin to the repository, please follow these steps.

Prepare Your Plugin

  1. Set Up Your Git Repository

    Make sure your plugin is a top-level repository. We don't accept plugins that are directories within other repositories.

  2. Add a Manifest and a Readme

    Write the README.md and package.yml files (explanation below), and add them to the repository at the top directory.

  3. Organize Your Files

    Make sure you respect the file structure (only the Source/ subdirectory is enforced, but it's a good idea to have them all).

    /
	Source/						#This can have subdirectories if you like
		YourPlugin.js				# main file
		YourPlugin.SomethingElse.js 		# extra component example
	Docs/
		YourPlugin.md				# plugin docs

    Docs are encouraged. There's a bundle for TextMate users to make this easier.

  4. Script Headers

    Each script in your /Source directory must have a specific header that includes metadata used by the forge. This header information is a YAML fragment with key/value sets of information that the will use for various features.

    First, an example (the order of the key/values does not matter): 

    /*
---
description: Element class, Elements class, and basic dom methods.

license: MIT-style

authors:
- Jimmy Dean
- Buck Kingsley

requires:
- localComponent1
- [localComponent2, localComponent3]
- externalPackage1/tag: component4
- externalPackage2/tag: [component1, component2]

provides: [Element, Elements, $, $$]

...
*/
    • description: a very brief, one line description of the contents of this file; try to keep this under 100 characters if you can.
    • license: the license for your plugin
    • authors: a list of authors for credit
    • requires: a list of the required components for your plugin to work
    • provides: a list of components that your plugin provides

    See the YAML Header footnotes below for additional tips and details.

  5. At least one Git tag in your repository is necessary. To tag a 0.1 release, for example, run these commands:

    git tag -a 0.1
git push --tags

  6. When everything looks good, click Add a new plugin (you must be logged in)

We also suggest taking a look at the Plugin Writing Guidelines.

README.md template (example)

Plugin Name
===========

What goes here is the description. Please don't make it too long. It can contain basic *styling*, **styling**, etc. 

If an image is found within the description, that becomes the screenshot of the plugin. Screenshots are optional but encouraged, given the plugin has some visual interaction. The screenshot can be of any size, but try to keep it of about 200x100.

![Screenshot](http://url_to_project_screenshot)

How to use
----------

We expect this section for every plugin. It just explains how to use your plugin.
Never should a plugin rely on a 3rd party link to explain its behavior or functionality. We need this to ensure that if a website is removed or becomes inaccessible, people can still enjoy your plugins' functionality.

It often includes code snippets, which are just indented pieces of text:

	var script = new MyScript()
	script.doSomething();

Syntax highlighting will be done automatically for you.

Screenshots
-----------

This section is optional, but encouraged if the plugin affords it. Just a list of images, one per line. We do the resizing, so use actual size screenshots.

![Screenshot 1](http://url_to_project_screenshot)
![Screenshot 2](http://url_to_project_screenshot)
![Screenshot 3](http://url_to_project_screenshot)
![Screenshot 4](http://url_to_project_screenshot)

Arbitrary section
-----------------

This is an arbitrary section. You can have as many of these as you want.
Some arbitrary section examples:

* FAQ
* Notes
* Misc
* Known issues

The name is up to you, but remember to keep it meaningful and simple. Arbitrary sections are always optional.

package.yml template (example)

name: Plugin Name
author: your forge username here
category: Interface
tags: [animation, canvas]
#docs: http://url.to.docs
#demo: http://url.to.demo
#current: 0.5

Notes about YAML

YAML validness is required. Some general tips and rules:

  • Don't use tabs, use spaces, or the file won't parse.
  • You can easily test your YAML before committing by pasting it into this online YAML tester.
  • For lists, two syntaxes are available: 
    authors: [Jimmy Dean, Buck Kingsley]
# OR
authors:
 - Jimmey Dean
 - Buck Kingsley

package.yml:

  • The category key has to be one valid, existing category. The list of categories is in the sidebar.
  • Keep tags meaningful. Tags that repeat categories names, or stuff like "Javascript", "Cool" are not valuable, and bound to be removed by moderators. Tags that depict techniques or technologies involved are encouraged, such as "canvas", "accessibility".
  • The current key points to an existing Git tag in your repository. It's optional, and the last Git tag is used if not present.
  • We recommend using GitHub pages for demo. This ensures that the demo page never goes offline or becomes inaccessible.

JavaScript files headers:

  • You can include other values if you like, but they won't be used by the forge. For example, if you wanted to include data used by your own script builders that's fine so long as these are present.
  • The provides list is a list of components in the current file. This allows you to have a file that might have several utilities and later allow you to split the file up. For example, if you had a file called "CustomSelectors.js" with custom selectors defined for "checked", "empty", and "selected" you consider making your "provides" values "[CustomSelectors.checked, CustomSelectors.empty, CustomSelectors.selected]" which would allow you to, at some future date, split the file up, or consolidate its contents with another file. This allows other plugins to require these components even if you reorganize them in the future.
  • The requires list is a list of components the current file needs in order to run. Each requirement list is preceded by the name of that component (as found in the Forge), the version (tag) your plugin works with, and then a list of components.
  • The names of MooTools Core and MooTools More are simply "core" and "more". All other plugin names are the short name at the end of their url (for instance, the Floom plugin's url is "http://mootools.net/plugins/p/floom" - so "floom" is it's name).
  • To refer to files within the current plugin simply name them with no repo:tag prefix.
  • Plugins can be included wholesale with an asterisk in single quotes, like so: 
    requires: 
  core/1.2.4: '*'

    It is not really recommended that you do this, as it will require users to perhaps load content they don't need in order to run your plugin. It is far better to include only the components that you need.

  • Dependency trees are implied, so if you require core/1.2.4:Class you are also requiring core/1.2.4:Core. You don't need to list implied dependencies, but you can if you like.
  • This dependency system will allow the forge to build a library for users, allowing them to select a group of plugins and then save the built library. Further, it will allow the forge and other tools to at some point in the future run automated tests and present working demos by including the required components. Having a valid dependency map is very important. The forge does not validate that your dependency map is correct, only that it is present (for now).