diff --git a/contributions/ServerCodeContributionsGuidelines/PluginCodeContributionsGuidelines.md b/contributions/ServerCodeContributionsGuidelines/PluginCodeContributionsGuidelines.md index 4be6e0f6eb..b35f1c4890 100644 --- a/contributions/ServerCodeContributionsGuidelines/PluginCodeContributionsGuidelines.md +++ b/contributions/ServerCodeContributionsGuidelines/PluginCodeContributionsGuidelines.md @@ -2,6 +2,246 @@ Please follow the given guidelines to make sure that your commit sails through the review process without any hiccups. +### Steps to create a new plugin + +At this point, we assume that you have Appsmith's server code base setup locally. If not, please check out [the guide here](../ServerSetup.md). + +1. Create a new maven module in the folder: `app/server/appsmith-plugins` via the command: +``` +mvn archetype:generate \ +-DgroupId=com.external.plugins \ +-DartifactId=helloWorldPlugin \ +-DarchetypeArtifactId=maven-archetype-quickstart \ +-DinteractiveMode=false +``` +Replace the `artifactId` with your plugin name. This tutorial will use `helloWorldPlugin` as a place-holder. + +This command will generate a folder called `helloWorldPlugin` with default source code in the `appsmith-plugins` directory. + +2. Navigate to your plugin code with your favourite IDE. + +3. Copy the required properties in the plugin's `pom.xml` file. Example: +``` + + UTF-8 + 11 + ${java.version} + ${java.version} + hello-world-name + com.external.plugins.HelloWorldPlugin + 1.0-SNAPSHOT + tech@appsmith.com + + +``` +Replace the properties `plugin.id` and `plugin.class` with your plugin name. + +4. Replace the default dependencies generated by maven with the following: +``` + + + org.pf4j + pf4j-spring + 0.7.0 + provided + + + + com.appsmith + interfaces + 1.0-SNAPSHOT + provided + + + + org.projectlombok + lombok + 1.18.8 + provided + + + + + junit + junit + 4.13.1 + test + + + + io.projectreactor + reactor-test + 3.2.11.RELEASE + test + + + org.mockito + mockito-core + 3.1.0 + test + + + +``` + +5. Add the `build` command to `pom.xml`: +``` + + + + + org.apache.maven.plugins + maven-shade-plugin + 3.2.4 + + false + + + + ${plugin.id} + ${plugin.class} + ${plugin.version} + ${plugin.provider} + + + + + + + package + + shade + + + + + + maven-dependency-plugin + + + copy-dependencies + package + + copy-dependencies + + + runtime + ${project.build.directory}/lib + + + + + + + +``` + +6. Add a file called `plugin.properties` with the following content: +``` +plugin.id=hello-world-plugin +plugin.class=com.external.plugins.HelloWorldPlugin +plugin.version=1.0-SNAPSHOT +plugin.provider=tech@appsmith.com +plugin.dependencies= +``` +Please remember that the `plugin.class` and `plugin.id` MUST be the same as the ones defined in your `pom.xml`. + +7. Navigate to your plugin's Java source folder `src/` and create a new class file `HelloWorldPlugin.java`. This is the same name as defined in your `pom.xml` property `plugin.class`. + +8. Ensure that the class has the following structure: + +``` +public class HelloWorldPlugin extends BasePlugin { + + public HelloWorldPlugin(PluginWrapper wrapper) { + super(wrapper); + } + + @Slf4j + @Extension + public static class HelloWorldPluginExecutor implements PluginExecutor { + } +} +``` +The `BasePlugin` & `PluginExecutor` classes define the basic operations of plugin execution + +9. Add the plugin to the DB so that the Appsmith platform understands that a new plugin has been created. This can be done via the `DatabaseChangelog.java` file. Eg: +``` + @ChangeSet(order = "076", id = "add-hello-world-plugin", author = "") + public void addHelloWorldPlugin(MongoTemplate mongoTemplate) { + Plugin plugin = new Plugin(); + plugin.setName("Hello World Plugin"); + plugin.setType(PluginType.DB); + plugin.setPackageName("hello-world-plugin"); + plugin.setUiComponent("DbEditorForm"); + plugin.setResponseType(Plugin.ResponseType.JSON); + plugin.setIconLocation("https://your-plugin-icon-location.png"); + plugin.setDocumentationLink("https://link-to-plugin-documentation.html"); + plugin.setDefaultInstall(true); + try { + mongoTemplate.insert(plugin); + } catch (DuplicateKeyException e) { + log.warn(plugin.getPackageName() + " already present in database."); + } + + installPluginToAllOrganizations(mongoTemplate, plugin.getId()); + } +``` + +10. Add the files `editor.json` and `form.json` in the `src/main/resources` folder. These JSON files are required to render the UI for your plugin. Samples are given below: +``` +# form.json + +{ + "form": [ + { + "sectionName": "Details", + "id": 1, + "children": [ + { + "label": "DB Username", + "configProperty": "datasourceConfiguration.authentication.username", + "controlType": "INPUT_TEXT", + "isRequired": true, + "placeholderText": "", + "initialValue": "" + }, + { + "label": "DB Password", + "configProperty": "datasourceConfiguration.authentication.password", + "controlType": "INPUT_TEXT", + "dataType": "PASSWORD", + "initialValue": "", + "encrypted": true + } + ] + } + ] +} + +# editor.json +{ + "editor": [ + { + "sectionName": "", + "id": 1, + "children": [ + { + "label": "", + "configProperty": "actionConfiguration.body", + "controlType": "QUERY_DYNAMIC_TEXT" + } + ] + } + ] +} + +``` + +11. Compile & run your code via the command: +``` +cd app/server && ./build.sh && cd scripts && ./start-dev-server.sh +``` ### Code Design As much as possible, please try to abide by the following code design: @@ -17,6 +257,7 @@ As much as possible, please try to abide by the following code design: For details, please see [this mapping](https://github.com/appsmithorg/appsmith/tree/release/static/editor.png) between `editor.json` and the rendered web page. + ### Package Dependency 1. We use `Maven` to manage package dependencies, hence please add all your dependencies in `POM` file as shown in this [pom.xml file](https://github.com/appsmithorg/appsmith/blob/release/app/server/appsmith-plugins/postgresPlugin/pom.xml) for postgreSQL plugin.