Welcome to Ametys 4!

Ametys is the JAVA Open Source CMS.

 
This page is the Javascript API reference for Ametys developpers.
You can also consult the Java API

 
Beginners should consider reading the documentations first to learn Ametys developments basics.  
Here are additional resources:

• Ask for help on the forum!
• Buy support or training!
• Report bug or make proposals!

For Ametys developers, how to write JS doc:

• Generality

  • /** A documentation */

  • /* An ignored comment */

  • The text MUST NOT start by a ( character. Except for (required) in specific cases.

• Property

  • /** @property {Type} propertyName A property */

  • /** @property {Type} [propertyName] An optional property */

  • /** @property {Type} [propertyName=defaultvalue] An optional property */

  • The default value can be a code or a value [stringProp="A value"] or [stringProp=Ametys.A_STRING_CONSTANT] or [numberProp=2]

  • /** @property {Type} propertyName (required) A required property */

  • /**
     * @property {Object} object Complex types can be documented this way:
     * @property {String} object.property The sub-property documentation
     * @property {String} [object.otherproperty=2] The sub-property documentation
     */

  • /** 
     * @property {Function} myfunction A function can be documented this way
     * @property {String} myfunction.param The first function param
     * @property {Boolean} myfunction.return The return value
     */

• Configurations

  • Configuration are the parameters of the config parameter of the constructor
  • /** @cfg {Type} myConf (required) My mandatory configuration

• Method

  • /** 
     * A method documentation
     * @param {Number} param The first param
     * @param {String/Object} [optionalParam] The optional params must be at the end
     * @param {String} optionalParam.name (required) When an object, this property is required
     * @return {Object} The returned value 
     * @return {String} return.name A property of the returned object 
     */
    

• Types

  • The {Type} is a classname of the documentation such as: Object, Number, Boolean String, RegExp, Function, Ext.form.field.Field...
  • A {Type} can also be: HTMLElement, XMLElement, NodeList, TextNode, XMLHttpRequest, Event, Window, Error.
  • A {Type} can be: Mixed or a list of / separated types: {Number/String}
  • A {Type} can a value: {"top"/"left"} is a type that can be one of those 2 string values.

• Event

  • /** 
     * @event eventName the documentation text
     * @param {String} target The 1st parameter passed to the listeners
     */

• Visibility

  • @private and @protected (public is the default visibility)
  • MUST be alone on their lines
  • MUST be at the beginning of the documentation

• Other tags

  • @abstract To denote an abstract class or method
  • @accessor On a @cfg to automatically generate the doc for getter and setter
  • @chainable On a method to specify it will return the same object. But you still need to document the return param
  • @deprecated To denote a deprecated method, class, property... @deprecated 4.3 No please use something else
  • @evented On a @cfg, will generate the associated change event documentation
  • @hide Will hide the given item from documentation. For example, when you automatically generate the gettes and setter, and you want to hide the setter.
  • @ignore Will be ignored
  • @inheritdoc Inherit the doc at this place. When you override an item, you can document nothing and all will be inherited OR document it all, and using @inheritdoc can help.
  • @localdoc Specify, that the doc will not be inhertied by subclassed. Usefull on @template methods.
  • @readonly Specify that the property should not be modfied
  • @removed Like @deprecated to specify something that does not exists anymore
  • @template A template method, is a method that has to be implemented. It is like an abstract, but can still give a part of the implementation.

• Link

  • /** Here is a {@link http://url link} to external url */

  • /** Here is a {@link Type link} to a type */

  • /** Here is a to a {@link Type} */

  • /** Type is an automatic link to a type */

  • You can link to member by changing Type to the following (in {@link} or in automatic links)
    • Type#cfg-myconfig
    • Type#property-myproperty
    • Type#static-property-myproperty
    • Type#method-mymethod
    • Type#static-method-mymethod
    • Type#event-myevent
    • Type#guessmember Will seek for a member of this name between the previous, but will warn if several members match the names
    • Type can be empty for a local link. E.g. #cfg-myconfig or {@link #event-myevent}

• Code

  • Code has to be indented and wrapped with blank lines

  • /**
     * Here is my class you can use this way
     *
     *        var code = Code.to("use my class");
     *        if (code == "is great")
     *        {
     *              return 42;
     *        }
     */
                                

• Document another class, method...

  • You can generate doc for somewhere else using @class, @method and @member