Applying Plugins to your Class Definition

ClassicalJS has a great plugin system, allowing you to add functionality to your Class definitions.
This page will cover how to apply plugins, as well as how to add persistent plugins to a Class.

If you're interested in creating your own plugin please refer to the plugin authoring page (TODO: link to plugin authoring page).

##Adding a plugin

Adding a plugin is a simple as including another script into your page:

<script src="/path/to/classical.js"></script>
<script src="/path/to/type.classical.js"></script> <!-- plugin script -->

The plugin's script should register itself on its own.

##Applying a plugin

Applying a plugin is as simple as calling the function:

var Person = 
    Class("Person")
        ...
         Type("String"); //a plugin that doesn't allow firstName to be something other than a String 
        Private ("firstName");
        ...
        ...
        ...

    End()

The Type plugin will now be applied on the private property "firstName" and it will be given the argument "String".
You can pass as many arguments as you want and they'll all be redirected to the Type plugin.

You might have to call a plugin after a property or a method. The author of the plugin should specify that.

     Type("String");
    Private("firstName");
     MakeGetterSetter(); //a plugin that adds public methods getFirstName() and setFirstName() to this Class

If you prefer to apply all your plugins with just one function call, you can use the Classes ._() method.

    Private("firstName");
     _({ type: "String", makeGetterSetter: true });

To read more about the ._() method, refer to this page (TODO: link to ._() page).

##Persistent Plugins

Sometimes you want to apply your plugins on all properties or methods of a Class. To do this, you use Persistent plugins.

var Person = 
    Class("Person")
        PersistentPlugins({
            Var: {
                makeGetterSetter: true //the makeGetterSetter plugin will be applied on all Variables of this Class
            }
        })

        ...
        ...
        ...

    End()

.PersistentPlugins should be passed an object containing one or many of the following keys:

• Var: Plugins that will be applied on all variables (does not have priority).
• PrivateVar: Plugins that will be applied on all private variables.
• ProtectedVar: Plugins that will be applied on all protected variables.
• PublicVar: Plugins that will be applied on all public variables.
• Fn: Plugins that will be applied on all functions(methods) (does not have priority).
• PrivateFn: Plugins that will be applied on all private functions(methods).
• ProtectedFn: Plugins that will be applied on all protected functions(methods).
• PublicFn: Plugins that will be applied on all public functions(methods).

Each of these keys should have an object as a value, similar to the one you pass to ._().
So a quick look at .() method page should be enough to know what kind of object PersistentPlugins expect (TODO: link to .() page).

You can also define PersistentPlugins on the library level, using Class.PersistentPlugins:

Class.PersistentPlugins({
    PublicFn: {
        chain: true //now all public methods will become chainable
    }
})

The format of the object you should pass to Class.PersistentPlugins is exactly the same as the one you would past to .PersistentPlugins.

##Disabling a plugin

To disable a plugin, just pass null to it:

Class("Person")
    ...
    PersistentPlugins({
        Var: {
            makeGetterSetter: true // apply the makeGetterSetter plugin on all vars
        }
    })
    ...
    Private("firstName");
     MakeGetterSetter(null); //the makeGetterSetter plugin won't be applied on "firstName"

    Private("lastName"); //but it will be applied on "lastName", (since it was set in the PersistentPlugins above)
    ...
    ...
End()

If you're using ._(), same thing:

Class("Person")
    ...
    PersistentPlugins({
        Var: {
            makeGetterSetter: true // apply the makeGetterSetter plugin on all vars
        }
    })
    ...
    Private("firstName");
     _({ makeGetterSetter: null }); //the makeGetterSetter plugin won't be applied on "firstName"

    Private("lastName"); //but it will be applied on "lastName", (since it was set in the PersistentPlugins above)
    ...
    ...
End()

#Things to keep in mind

• If not using ._(), the placement of the PluginInvocation() matters. It can be either before or after a property/method. The author of the plugin decides that. (Example: Type plugin comes before a property declaration, but makeGetterSetter plugin comes after)

• The name of the PluginInvocation() function could differ from the key you would use in ._(). The author of the plugin decides that. (Example: you would use Type("String") but ._({ type: "String }))

• The order in which you invoke the plugins does not matter. Each one has a priority (decided by the author) and the plugins are later on called depending on their priority.

• There are also Void plugins, that don't get applied on any property/method, but on the whole Class. This gives full control for plugins authors, allowing them to add functionalities like Static methods/properties and Interfaces, etc. The plugin author should explain the behavior of his void plugin, and if other plugins can be able to it.