Changes extensions
Last updated
Last updated
This type of extension allows us to extend the set of changes that the API specifies (and that the IDE will expect to be present). Hence, specifications retrieved from this endpoint will enlarge the list of options available on the IDE.
Of course, every change defined as an extension must be supported by the target system.
As in the case of pre-defined changes, they might result in errors. These will provide the same information explained .
A change extension must be like this:
Where:
type as these are change extensions this property is change.
properties contains the actual properties of the change to be posted.
parameters (optional) a list of parameters that will be prompted to the user to fill some of the properties (see below).
A parameter is specified in the following way:
where type is either text, number, boolean or options (this type should be accompanied with a property optinos with the options to provide).
needsConfirmation (optional) specifies whether the change should be confirmed by the user. By default is false..
Here, the meta-model object to which the change refers is a class named MyClass, and to which the change aims at renaming it as OurClass, renaming also all references (i.e., methods referencing MyClass).
Now, lets express our pre-defined class rename change as the definition of a new extended one, using a different change type and making renameReferences modifiable by the user through another parameter (with true as a default value).
As said above, properties represent the actual properties the change will have. Their values however, will be processed to obtaing the actual values in the following way.
Note that an element attribute can be immersed in a wider string. Moreover, there could be more than one attribute.
As a general rule, the property value will be the result of replacing every "dot" expression (expression between curly brakets), leaving the rest of the string as it is. For example, the actual value of a property whose value is specified as {element.methodClass} >> #{element.selector}, applicable on a method element whose methodClass is Point and its selector is x, will be Point >> x.
If the value contains {parameters.xxxx}, the actual value will be extracted from the parameter with the name given by what follows the dot (xxxx). In our example, the parameter named newName will be first prompted to the user, and once the user has provided a value for it, such value will be used for the property.
As in the case of element attributes, there might be more than one occurrence of such pattern, and those will be treated as explained above.
Finally, if none of the above conditions hold, the value of a property is treated as a fixed value. This is the case of the properties type and renameReferences for which the values are RenameClass and true respectively.
As shown in our example, a parameter has the following form:
Where,
type specifies how the parameter will be prompted to the user. At the moment of writing this document it can be text, number or boolean.
options (optional) provides a list of alternatives. This can be either a fixed list, or a dynamic one. By the moment, there are only two possibilities for the latter: packages or classes, to provide the user with the list of the names of existing packages and classes, respectively.
label will be used to prompt the user for a value.
defaultValue (optional) is the default value presented to the user. In the case of a string, it can contain zero or more attribute expressions ({element.xxxx}). (In our example, the default value is the current name of the class, and so it is defined as {element.name}).
With this specification, users will find an option My own class renaming withing the class menu options, and when they hit it, they will be prompted for New name, with the current name as the default value, and whether they want to rename references or not. Should they accept the prompt with the option "Rename references" unselected, the IDE will post the following change:
Lets suppose we want to extend method options to include one for moving the selected method to its superclass (available in some IDEs such as Pharo's one). We should include the following extension:
And make sure our target system manages MoveUpMethod change properly.
The rest of the basic properties are described .
Lets take a look at one of the changes pre-defined in the API: RenameClass. As detailed , this change must look like the following in order to be valid for its application:
If the value of a property contains {element.xxxx}, the actual value will be extracted from the attribute corresponding to what follows the dot (xxxx). Here, element represents the meta-model object from which the change is triggered (most likely the object selected in IDE). In the example, the value for className property is {element.name}, meaning that the actual value will be extracted from the attribute name of the target element (lets asume MyClass is selected). Valid attributes can be extracted from the corresponding endpoints in the documentation (, , , , ).