From 30e54f26069079d902f500cea10f65c3c3d691fb Mon Sep 17 00:00:00 2001 From: Peter Mucha Date: Thu, 14 Jul 2022 15:52:26 +0200 Subject: [PATCH] add dev intro --- content/en/docs/Development/_index.md | 10 + content/en/docs/Development/model.md | 82 ++++ content/en/docs/Development/setup.md | 73 ++++ content/en/docs/_index.md | 2 +- docs/docs/_print/index.html | 286 +++++++++++-- docs/docs/development/_print/index.html | 448 +++++++++++++++++++ docs/docs/development/index.html | 427 ++++++++++++++++++ docs/docs/development/index.xml | 150 +++++++ docs/docs/development/model/index.html | 449 +++++++++++++++++++ docs/docs/development/setup/index.html | 452 ++++++++++++++++++++ docs/docs/features/index.html | 11 +- docs/docs/features/slack/index.html | 11 +- docs/docs/index.html | 21 +- docs/docs/index.xml | 133 ++++++ docs/docs/plugins/authentication/index.html | 11 +- docs/docs/plugins/cassandra/index.html | 11 +- docs/docs/plugins/cli/index.html | 11 +- docs/docs/plugins/explore/index.html | 11 +- docs/docs/plugins/graphql/index.html | 11 +- docs/docs/plugins/grpc/index.html | 11 +- docs/docs/plugins/index.html | 11 +- docs/docs/plugins/jdbc/index.html | 11 +- docs/docs/plugins/note/index.html | 11 +- docs/docs/plugins/privatebin/index.html | 11 +- docs/docs/plugins/rest/index.html | 11 +- docs/docs/plugins/scripting/index.html | 11 +- docs/docs/plugins/sio/index.html | 11 +- docs/docs/plugins/sync-git/index.html | 11 +- docs/docs/plugins/test/index.html | 11 +- docs/docs/plugins/ws/index.html | 11 +- docs/sitemap.xml | 6 + 31 files changed, 2679 insertions(+), 58 deletions(-) create mode 100755 content/en/docs/Development/_index.md create mode 100644 content/en/docs/Development/model.md create mode 100644 content/en/docs/Development/setup.md create mode 100644 docs/docs/development/_print/index.html create mode 100644 docs/docs/development/index.html create mode 100644 docs/docs/development/index.xml create mode 100644 docs/docs/development/model/index.html create mode 100644 docs/docs/development/setup/index.html diff --git a/content/en/docs/Development/_index.md b/content/en/docs/Development/_index.md new file mode 100755 index 0000000..d31d025 --- /dev/null +++ b/content/en/docs/Development/_index.md @@ -0,0 +1,10 @@ + +--- +title: "Milkman Plugin Development" +linkTitle: "Developing Plugins" +--- + +{{% pageinfo %}} +This section shows some information on how to develop your own plugins for milkman +{{% /pageinfo %}} + diff --git a/content/en/docs/Development/model.md b/content/en/docs/Development/model.md new file mode 100644 index 0000000..ea09096 --- /dev/null +++ b/content/en/docs/Development/model.md @@ -0,0 +1,82 @@ +--- +title: "Internal Model" +linkTitle: "Internal Model" +description: "Description of domain model of milkman" + +--- + +Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first. + +# Getting Started +A [sample plugin](https://github.com/warmuuh/milkman/tree/master/milkman-note) was created that shows how to add an Aspect Tab to a Request. + +if you want to setup a new project, an exemplary pom can be found [here](/docs/development/setup). + +# Data Model + +![img](http://www.gravizo.com/svg?@startuml;object%20Workspace;object%20Environment;Environment%20:%20isGlobal;Workspace%20o--%20%22*%22%20Environment;object%20Collection;Workspace%20o--%20%22*%22%20Collection;object%20Request;Collection%20o--%20%22*%22%20Request;%20Request%20--%3E%20HtmlRequest%20;%20Request%20--%3E%20SqlRequest%20;Request%20o-%20%22*%22%20RequestAspect;RequestAspect%20--%3E%20HttpHeaderRequestAspect;RequestAspect%20--%3E%20HttpBodyRequestAspect;@enduml) + +The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. +A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method. + +A request can also contain several `RequestAspects` which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes. + +All Aspects and the container gets serialized using Jackson and stored in a local Database. + +# Extension Points + +Milkman uses [SPI](https://docs.oracle.com/javase/tutorial/ext/basics/spi.html) for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the `/plugin` folder to have milkman pick up your plugin. + +## RequestAspectsPlugin + +A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect). + +## ContentTypePlugin + +A content type plugin is used to format and highlight content based on a mime-type. + +## RequestTypePlugin + +A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. +This plugin has to provide a small editor for basic attributes of the request as well. + +## ImporterPlugin + +a plugin that imports things into the current workspace, such as collections, requests, environments. + +## OptionPageProvider + +a plugin to provide a UI for editing options of a "logical" plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database. + +## UI Theme Plugin + +provides an application-theme css and a syntax-theme css for styling. + +## Workspace Synchronizer Plugin + +provides a mechanism to synchronize the workspace with some external mechanism + +## Request Export Plugin + +extension point for adding export methods to a request-type. + +## Collection Export Plugin + +extension point for adding export methods to a collection. + +# Persistence +All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize. + +# Common Components +Some common components are provided by milkman to make development of plugins easier: + + * TableEditor: a table that might or might not be editable. used for editing headers or environments or such. + * ContentEditor: a content editor that supports highlighting and formatting + * Dialogs: some common dialogs, such as credentialsInput or StringInput. + +# Testing +milkman uses TestFX for testing. A [sample test](https://github.com/warmuuh/milkman/blob/master/milkman-note/src/test/java/milkman/plugin/note/NotesAspectEditorTest.java) can be seen in the notes plugin. + +# Gotchas +JavaFX uses a lot of weak references. That means, if you don't keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don't work. +You can use `setUserData` in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time. diff --git a/content/en/docs/Development/setup.md b/content/en/docs/Development/setup.md new file mode 100644 index 0000000..6e371e6 --- /dev/null +++ b/content/en/docs/Development/setup.md @@ -0,0 +1,73 @@ +--- +title: "Development Setup" +linkTitle: "Setup" +description: "Description of how to setup your environment" +--- + +for creating a new plugin, you can use following pom: + + + +```xml + + 4.0.0 + + ... + ... + ... + + + + + com.github.warmuuh.milkman + milkman + ... + provided + + + + com.github.warmuuh.milkman + milkman-rest + ... + provided + + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + 2.6 + + + jar-with-dependencies + + false + + + + assemble-all + package + + single + + + + + + + + + + + jitpack.io + https://jitpack.io + + + + +``` diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 8f842c0..2ff03fc 100755 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -58,7 +58,7 @@ some resolved issues and FAQs are available in the [wiki](https://github.com/war * **JavaFX Application:** as in: *fast* (compared to electron at least :D) and skinn-able (you can extend milkman with your own themes using simple CSS). * **Commandline Interface:** there is a [command line interface](plugins/cli) for Milkman which allows to edit/execute requests on your command line. * **Slack Command:** you can use `/milkman ` in slack to share requests in a better way. [More Info](features/slack). - * [Some more details](docs/features.md) of the core application features, such as hotkeys etc. + * [Some more details](features/) of the core application features, such as hotkeys etc. # Existing Plugins: diff --git a/docs/docs/_print/index.html b/docs/docs/_print/index.html index d898354..b384ac1 100644 --- a/docs/docs/_print/index.html +++ b/docs/docs/_print/index.html @@ -148,7 +148,7 @@

Documentation

-
  • 1: Advanced Features
    • +
  • 1: Milkman Plugin Development
    • @@ -163,7 +163,15 @@

    Documentation

    -
  • 1.1: Slack Integration
    • +
  • 1.1: Internal Model
    • + + + + + + + +
  • 1.2: Development Setup
    • @@ -175,7 +183,7 @@

    Documentation

    -
  • 2: Milkman Plugins
    • +
  • 2: Advanced Features
    • @@ -190,23 +198,34 @@

    Documentation

    -
  • 2.1: Milkman Auth Plugin
    • +
  • 2.1: Slack Integration
    • + + + + -
  • 2.2: Milkman Cassandra Plugin
    • +
  • 3: Milkman Plugins
    • +

    Existing Plugins:

    Note: see respective plugin folder for more details

    @@ -458,7 +493,184 @@

    Changes

    -

    1 - Advanced Features

    +

    1 - Milkman Plugin Development

    + + + +
    +

    This section shows some information on how to develop your own plugins for milkman

    + +
    + + +
    + + + + + + + + + + + + + + + + + + + +
    + +

    1.1 - Internal Model

    +
    Description of domain model of milkman
    +

    Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.

    +

    Getting Started

    +

    A sample plugin was created that shows how to add an Aspect Tab to a Request.

    +

    if you want to setup a new project, an exemplary pom can be found here.

    +

    Data Model

    +

    img

    +

    The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. +A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method.

    +

    A request can also contain several RequestAspects which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes.

    +

    All Aspects and the container gets serialized using Jackson and stored in a local Database.

    +

    Extension Points

    +

    Milkman uses SPI for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the /plugin folder to have milkman pick up your plugin.

    +

    RequestAspectsPlugin

    +

    A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect).

    +

    ContentTypePlugin

    +

    A content type plugin is used to format and highlight content based on a mime-type.

    +

    RequestTypePlugin

    +

    A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. +This plugin has to provide a small editor for basic attributes of the request as well.

    +

    ImporterPlugin

    +

    a plugin that imports things into the current workspace, such as collections, requests, environments.

    +

    OptionPageProvider

    +

    a plugin to provide a UI for editing options of a “logical” plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database.

    +

    UI Theme Plugin

    +

    provides an application-theme css and a syntax-theme css for styling.

    +

    Workspace Synchronizer Plugin

    +

    provides a mechanism to synchronize the workspace with some external mechanism

    +

    Request Export Plugin

    +

    extension point for adding export methods to a request-type.

    +

    Collection Export Plugin

    +

    extension point for adding export methods to a collection.

    +

    Persistence

    +

    All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize.

    +

    Common Components

    +

    Some common components are provided by milkman to make development of plugins easier:

    +
      +
    • TableEditor: a table that might or might not be editable. used for editing headers or environments or such.
      • +
    • ContentEditor: a content editor that supports highlighting and formatting
      • +
    • Dialogs: some common dialogs, such as credentialsInput or StringInput.
      • +
    +

    Testing

    +

    milkman uses TestFX for testing. A sample test can be seen in the notes plugin.

    +

    Gotchas

    +

    JavaFX uses a lot of weak references. That means, if you don’t keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don’t work. +You can use setUserData in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time.

    + +
    + + + + + + + + + + + +
    + +

    1.2 - Development Setup

    +
    Description of how to setup your environment
    +

    for creating a new plugin, you can use following pom:

    +
    <project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	
+	<groupId>...</groupId>
+	<artifactId>...</artifactId>
+	<version>...</version>
+	
+	
+	<dependencies>
+		<dependency>
+			<groupId>com.github.warmuuh.milkman</groupId>
+			<artifactId>milkman</artifactId>
+			<version>...</version>
+			<scope>provided</scope>
+		</dependency>
+		<!-- and for refering to plugins of milkman: -->
+		<dependency> 
+			<groupId>com.github.warmuuh.milkman</groupId> 
+			<artifactId>milkman-rest</artifactId> 
+			<version>...</version> 
+			<scope>provided</scope>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<!-- for packaging all your dependencies into one jar, excluding provided ones -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-assembly-plugin</artifactId>
+				<version>2.6</version>
+				<configuration>
+					<descriptorRefs>
+						<descriptorRef>jar-with-dependencies</descriptorRef>
+					</descriptorRefs>
+					<appendAssemblyId>false</appendAssemblyId>
+				</configuration>
+				<executions>
+					<execution>
+						<id>assemble-all</id>
+						<phase>package</phase>
+						<goals>
+							<goal>single</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+	
+	
+	<repositories>
+		<repository>
+			<id>jitpack.io</id>
+			<url>https://jitpack.io</url>
+		</repository>
+	</repositories>
+
+</project>
+
    +
    + + + + + + + + + + + + + + + +
    + +

    2 - Advanced Features

    Description of some more advanced Features of Milkman
    @@ -531,7 +743,7 @@

    Libraries

    -

    1.1 - Slack Integration

    +

    2.1 - Slack Integration

    Slack-integration for milkman
    @@ -627,7 +839,7 @@

    Planned

    -

    2 - Milkman Plugins

    +

    3 - Milkman Plugins

    @@ -660,7 +872,7 @@

    2 - Milkman Plugins

    -

    2.1 - Milkman Auth Plugin

    +

    3.1 - Milkman Auth Plugin

    Contains key-types for authentication, such as oauth-authentication
    @@ -714,7 +926,7 @@

    Remarks

    -

    2.2 - Milkman Cassandra Plugin

    +

    3.2 - Milkman Cassandra Plugin

    Introduces Cql Requests to Milkman using cassandra datastax driver.
    @@ -790,7 +1002,7 @@

    Features

    -

    2.3 - Milkman Commandline Interface

    +

    3.3 - Milkman Commandline Interface

    This is an experimental interactive command line interface for plugin.
    @@ -873,7 +1085,7 @@

    Screenshot

    -

    2.4 - Milkman Explore Plugin

    +

    3.4 - Milkman Explore Plugin

    JMesPath exploring for your json response.
    @@ -919,7 +1131,7 @@

    Screenshot

    -

    2.5 - Milkman GraphQL Plugin

    +

    3.5 - Milkman GraphQL Plugin

    Allows to craft GraphQL requests.
    @@ -966,7 +1178,7 @@

    Screenshot

    -

    2.6 - Milkman Grpc Plugin

    +

    3.6 - Milkman Grpc Plugin

    Grpc Plugin for communication with Grpc Servers.
    @@ -1019,7 +1231,7 @@

    Client Streaming

    -

    2.7 - Milkman Http Plugin

    +

    3.7 - Milkman Http Plugin

    Allows to share requests etc via Privatebin.
    @@ -1074,7 +1286,7 @@

    Features

    -

    2.8 - Milkman Note Plugin

    +

    3.8 - Milkman Note Plugin

    Introduces Sql Requests to Milkman using JDBC.
    @@ -1117,7 +1329,7 @@

    Screenshot

    -

    2.9 - Milkman Privatebin Plugin

    +

    3.9 - Milkman Privatebin Plugin

    Allows to share requests etc via Privatebin.
    @@ -1166,7 +1378,7 @@

    Features

    -

    2.10 - Milkman Scripting Plugin

    +

    3.10 - Milkman Scripting Plugin

    Ads Pre- and Post-scripts to requests
    @@ -1261,7 +1473,7 @@

    API

    -

    2.11 - Milkman Socket.IO Plugin

    +

    3.11 - Milkman Socket.IO Plugin

    Support for Socket.IO transport
    @@ -1311,7 +1523,7 @@

    Note

    -

    2.12 - Milkman Jdbc Plugin

    +

    3.12 - Milkman Jdbc Plugin

    Introduces Sql Requests to Milkman using JDBC.
    @@ -1360,7 +1572,7 @@

    Features

    -

    2.13 - Milkman Git Sync Plugin

    +

    3.13 - Milkman Git Sync Plugin

    Team Synchronization via Git
    @@ -1411,7 +1623,7 @@

    Remark

    -

    2.14 - Milkman Test Plugin

    +

    3.14 - Milkman Test Plugin

    Testing of Requests
    @@ -1451,7 +1663,7 @@

    Environment

    -

    2.15 - Milkman Websocket Plugin

    +

    3.15 - Milkman Websocket Plugin

    Support for websocket transport
    diff --git a/docs/docs/development/_print/index.html b/docs/docs/development/_print/index.html new file mode 100644 index 0000000..9256533 --- /dev/null +++ b/docs/docs/development/_print/index.html @@ -0,0 +1,448 @@ + + + + + + + + + + + + + + + + + + + + + + +Milkman Plugin Development | Milkman + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    +
    +
    +
    +
    + + + + + +
    +
    +

    +This is the multi-page printable view of this section. +Click here to print. +

    +Return to the regular view of this page. +

    +
    + + + +

    Milkman Plugin Development

    + + + + + + + + +
    + + +
    +

    This section shows some information on how to develop your own plugins for milkman

    + +
    + + +
    +
    + + + + + + + + + + + + + + + + +
    + +

    1 - Internal Model

    +
    Description of domain model of milkman
    +

    Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.

    +

    Getting Started

    +

    A sample plugin was created that shows how to add an Aspect Tab to a Request.

    +

    if you want to setup a new project, an exemplary pom can be found here.

    +

    Data Model

    +

    img

    +

    The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. +A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method.

    +

    A request can also contain several RequestAspects which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes.

    +

    All Aspects and the container gets serialized using Jackson and stored in a local Database.

    +

    Extension Points

    +

    Milkman uses SPI for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the /plugin folder to have milkman pick up your plugin.

    +

    RequestAspectsPlugin

    +

    A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect).

    +

    ContentTypePlugin

    +

    A content type plugin is used to format and highlight content based on a mime-type.

    +

    RequestTypePlugin

    +

    A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. +This plugin has to provide a small editor for basic attributes of the request as well.

    +

    ImporterPlugin

    +

    a plugin that imports things into the current workspace, such as collections, requests, environments.

    +

    OptionPageProvider

    +

    a plugin to provide a UI for editing options of a “logical” plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database.

    +

    UI Theme Plugin

    +

    provides an application-theme css and a syntax-theme css for styling.

    +

    Workspace Synchronizer Plugin

    +

    provides a mechanism to synchronize the workspace with some external mechanism

    +

    Request Export Plugin

    +

    extension point for adding export methods to a request-type.

    +

    Collection Export Plugin

    +

    extension point for adding export methods to a collection.

    +

    Persistence

    +

    All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize.

    +

    Common Components

    +

    Some common components are provided by milkman to make development of plugins easier:

    +
      +
    • TableEditor: a table that might or might not be editable. used for editing headers or environments or such.
      • +
    • ContentEditor: a content editor that supports highlighting and formatting
      • +
    • Dialogs: some common dialogs, such as credentialsInput or StringInput.
      • +
    +

    Testing

    +

    milkman uses TestFX for testing. A sample test can be seen in the notes plugin.

    +

    Gotchas

    +

    JavaFX uses a lot of weak references. That means, if you don’t keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don’t work. +You can use setUserData in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time.

    + +
    + + + + + + + + + + + +
    + +

    2 - Development Setup

    +
    Description of how to setup your environment
    +

    for creating a new plugin, you can use following pom:

    +
    <project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	
+	<groupId>...</groupId>
+	<artifactId>...</artifactId>
+	<version>...</version>
+	
+	
+	<dependencies>
+		<dependency>
+			<groupId>com.github.warmuuh.milkman</groupId>
+			<artifactId>milkman</artifactId>
+			<version>...</version>
+			<scope>provided</scope>
+		</dependency>
+		<!-- and for refering to plugins of milkman: -->
+		<dependency> 
+			<groupId>com.github.warmuuh.milkman</groupId> 
+			<artifactId>milkman-rest</artifactId> 
+			<version>...</version> 
+			<scope>provided</scope>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<!-- for packaging all your dependencies into one jar, excluding provided ones -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-assembly-plugin</artifactId>
+				<version>2.6</version>
+				<configuration>
+					<descriptorRefs>
+						<descriptorRef>jar-with-dependencies</descriptorRef>
+					</descriptorRefs>
+					<appendAssemblyId>false</appendAssemblyId>
+				</configuration>
+				<executions>
+					<execution>
+						<id>assemble-all</id>
+						<phase>package</phase>
+						<goals>
+							<goal>single</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+	
+	
+	<repositories>
+		<repository>
+			<id>jitpack.io</id>
+			<url>https://jitpack.io</url>
+		</repository>
+	</repositories>
+
+</project>
+
    +
    + + + + + + + + + +
    +
    +
    + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/docs/development/index.html b/docs/docs/development/index.html new file mode 100644 index 0000000..85c6f90 --- /dev/null +++ b/docs/docs/development/index.html @@ -0,0 +1,427 @@ + + + + + + + + + + + + + + + + + + + + + + +Milkman Plugin Development | Milkman + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    +
    +
    +
    + + +
    + + + + + +
    +

    Milkman Plugin Development

    + +
    + + + + + + + + + + + + + + + +
    + + +
    +

    This section shows some information on how to develop your own plugins for milkman

    + +
    + + +
    + + + + + + + + +
    + + +
    +
    + Internal Model +
    +

    Description of domain model of milkman

    +
    + + +
    +
    + Development Setup +
    +

    Description of how to setup your environment

    +
    + + +
    + + + + +
    + +
    +
    +
    + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/docs/development/index.xml b/docs/docs/development/index.xml new file mode 100644 index 0000000..cbef6b6 --- /dev/null +++ b/docs/docs/development/index.xml @@ -0,0 +1,150 @@ + + + Milkman – Milkman Plugin Development + https://milkman.dev/docs/development/ + Recent content in Milkman Plugin Development on Milkman + Hugo -- gohugo.io + + + + + + + + + + + Docs: Internal Model + https://milkman.dev/docs/development/model/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://milkman.dev/docs/development/model/ + + + + <p>Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.</p> +<h1 id="getting-started">Getting Started</h1> +<p>A <a href="https://github.com/warmuuh/milkman/tree/master/milkman-note">sample plugin</a> was created that shows how to add an Aspect Tab to a Request.</p> +<p>if you want to setup a new project, an exemplary pom can be found <a href="https://milkman.dev/docs/development/setup">here</a>.</p> +<h1 id="data-model">Data Model</h1> +<p><img src="http://www.gravizo.com/svg?@startuml;object%20Workspace;object%20Environment;Environment%20:%20isGlobal;Workspace%20o--%20%22*%22%20Environment;object%20Collection;Workspace%20o--%20%22*%22%20Collection;object%20Request;Collection%20o--%20%22*%22%20Request;%20Request%20--%3E%20HtmlRequest%20;%20Request%20--%3E%20SqlRequest%20;Request%20o-%20%22*%22%20RequestAspect;RequestAspect%20--%3E%20HttpHeaderRequestAspect;RequestAspect%20--%3E%20HttpBodyRequestAspect;@enduml" alt="img"></p> +<p>The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. +A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method.</p> +<p>A request can also contain several <code>RequestAspects</code> which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes.</p> +<p>All Aspects and the container gets serialized using Jackson and stored in a local Database.</p> +<h1 id="extension-points">Extension Points</h1> +<p>Milkman uses <a href="https://docs.oracle.com/javase/tutorial/ext/basics/spi.html">SPI</a> for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the <code>/plugin</code> folder to have milkman pick up your plugin.</p> +<h2 id="requestaspectsplugin">RequestAspectsPlugin</h2> +<p>A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect).</p> +<h2 id="contenttypeplugin">ContentTypePlugin</h2> +<p>A content type plugin is used to format and highlight content based on a mime-type.</p> +<h2 id="requesttypeplugin">RequestTypePlugin</h2> +<p>A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. +This plugin has to provide a small editor for basic attributes of the request as well.</p> +<h2 id="importerplugin">ImporterPlugin</h2> +<p>a plugin that imports things into the current workspace, such as collections, requests, environments.</p> +<h2 id="optionpageprovider">OptionPageProvider</h2> +<p>a plugin to provide a UI for editing options of a &ldquo;logical&rdquo; plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database.</p> +<h2 id="ui-theme-plugin">UI Theme Plugin</h2> +<p>provides an application-theme css and a syntax-theme css for styling.</p> +<h2 id="workspace-synchronizer-plugin">Workspace Synchronizer Plugin</h2> +<p>provides a mechanism to synchronize the workspace with some external mechanism</p> +<h2 id="request-export-plugin">Request Export Plugin</h2> +<p>extension point for adding export methods to a request-type.</p> +<h2 id="collection-export-plugin">Collection Export Plugin</h2> +<p>extension point for adding export methods to a collection.</p> +<h1 id="persistence">Persistence</h1> +<p>All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize.</p> +<h1 id="common-components">Common Components</h1> +<p>Some common components are provided by milkman to make development of plugins easier:</p> +<ul> +<li>TableEditor: a table that might or might not be editable. used for editing headers or environments or such.</li> +<li>ContentEditor: a content editor that supports highlighting and formatting</li> +<li>Dialogs: some common dialogs, such as credentialsInput or StringInput.</li> +</ul> +<h1 id="testing">Testing</h1> +<p>milkman uses TestFX for testing. A <a href="https://github.com/warmuuh/milkman/blob/master/milkman-note/src/test/java/milkman/plugin/note/NotesAspectEditorTest.java">sample test</a> can be seen in the notes plugin.</p> +<h1 id="gotchas">Gotchas</h1> +<p>JavaFX uses a lot of weak references. That means, if you don&rsquo;t keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don&rsquo;t work. +You can use <code>setUserData</code> in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time.</p> + + + + + + Docs: Development Setup + https://milkman.dev/docs/development/setup/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://milkman.dev/docs/development/setup/ + + + + <p>for creating a new plugin, you can use following pom:</p> +<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">&lt;project</span> <span style="color:#c4a000">xmlns=</span><span style="color:#4e9a06">&#34;http://maven.apache.org/POM/4.0.0&#34;</span> +</span></span><span style="display:flex;"><span> <span style="color:#c4a000">xmlns:xsi=</span><span style="color:#4e9a06">&#34;http://www.w3.org/2001/XMLSchema-instance&#34;</span> +</span></span><span style="display:flex;"><span> <span style="color:#c4a000">xsi:schemaLocation=</span><span style="color:#4e9a06">&#34;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&#34;</span><span style="color:#204a87;font-weight:bold">&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;modelVersion&gt;</span>4.0.0<span style="color:#204a87;font-weight:bold">&lt;/modelVersion&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;dependencies&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>com.github.warmuuh.milkman<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>milkman<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;scope&gt;</span>provided<span style="color:#204a87;font-weight:bold">&lt;/scope&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#8f5902;font-style:italic">&lt;!-- and for refering to plugins of milkman: --&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>com.github.warmuuh.milkman<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>milkman-rest<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;scope&gt;</span>provided<span style="color:#204a87;font-weight:bold">&lt;/scope&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/dependencies&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;build&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;plugins&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#8f5902;font-style:italic">&lt;!-- for packaging all your dependencies into one jar, excluding provided ones --&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;plugin&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>org.apache.maven.plugins<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>maven-assembly-plugin<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>2.6<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;configuration&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;descriptorRefs&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;descriptorRef&gt;</span>jar-with-dependencies<span style="color:#204a87;font-weight:bold">&lt;/descriptorRef&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/descriptorRefs&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;appendAssemblyId&gt;</span>false<span style="color:#204a87;font-weight:bold">&lt;/appendAssemblyId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/configuration&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;executions&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;execution&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;id&gt;</span>assemble-all<span style="color:#204a87;font-weight:bold">&lt;/id&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;phase&gt;</span>package<span style="color:#204a87;font-weight:bold">&lt;/phase&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;goals&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;goal&gt;</span>single<span style="color:#204a87;font-weight:bold">&lt;/goal&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/goals&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/execution&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/executions&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/plugin&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/plugins&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/build&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;repositories&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;repository&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;id&gt;</span>jitpack.io<span style="color:#204a87;font-weight:bold">&lt;/id&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;url&gt;</span>https://jitpack.io<span style="color:#204a87;font-weight:bold">&lt;/url&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/repository&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/repositories&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">&lt;/project&gt;</span> +</span></span></code></pre></div> + + + + + diff --git a/docs/docs/development/model/index.html b/docs/docs/development/model/index.html new file mode 100644 index 0000000..5e06830 --- /dev/null +++ b/docs/docs/development/model/index.html @@ -0,0 +1,449 @@ + + + + + + + + + + + + + + + + + + + + +Internal Model | Milkman + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    +
    +
    +
    + + +
    + + + + + +
    +

    Internal Model

    +
    Description of domain model of milkman
    +
    + + + + + + + + + + + + + + + +
    +

    Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.

    +

    Getting Started

    +

    A sample plugin was created that shows how to add an Aspect Tab to a Request.

    +

    if you want to setup a new project, an exemplary pom can be found here.

    +

    Data Model

    +

    img

    +

    The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. +A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method.

    +

    A request can also contain several RequestAspects which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes.

    +

    All Aspects and the container gets serialized using Jackson and stored in a local Database.

    +

    Extension Points

    +

    Milkman uses SPI for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the /plugin folder to have milkman pick up your plugin.

    +

    RequestAspectsPlugin

    +

    A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect).

    +

    ContentTypePlugin

    +

    A content type plugin is used to format and highlight content based on a mime-type.

    +

    RequestTypePlugin

    +

    A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. +This plugin has to provide a small editor for basic attributes of the request as well.

    +

    ImporterPlugin

    +

    a plugin that imports things into the current workspace, such as collections, requests, environments.

    +

    OptionPageProvider

    +

    a plugin to provide a UI for editing options of a “logical” plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database.

    +

    UI Theme Plugin

    +

    provides an application-theme css and a syntax-theme css for styling.

    +

    Workspace Synchronizer Plugin

    +

    provides a mechanism to synchronize the workspace with some external mechanism

    +

    Request Export Plugin

    +

    extension point for adding export methods to a request-type.

    +

    Collection Export Plugin

    +

    extension point for adding export methods to a collection.

    +

    Persistence

    +

    All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize.

    +

    Common Components

    +

    Some common components are provided by milkman to make development of plugins easier:

    +
      +
    • TableEditor: a table that might or might not be editable. used for editing headers or environments or such.
      • +
    • ContentEditor: a content editor that supports highlighting and formatting
      • +
    • Dialogs: some common dialogs, such as credentialsInput or StringInput.
      • +
    +

    Testing

    +

    milkman uses TestFX for testing. A sample test can be seen in the notes plugin.

    +

    Gotchas

    +

    JavaFX uses a lot of weak references. That means, if you don’t keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don’t work. +You can use setUserData in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time.

    + + + + +
    + + +
    +
    +
    + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/docs/development/setup/index.html b/docs/docs/development/setup/index.html new file mode 100644 index 0000000..944526e --- /dev/null +++ b/docs/docs/development/setup/index.html @@ -0,0 +1,452 @@ + + + + + + + + + + + + + + + + + + + + +Development Setup | Milkman + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    +
    +
    +
    + + +
    + + + + + +
    +

    Development Setup

    +
    Description of how to setup your environment
    +
    + + + + + + + + + + + + + + + +
    +

    for creating a new plugin, you can use following pom:

    +
    <project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	
+	<groupId>...</groupId>
+	<artifactId>...</artifactId>
+	<version>...</version>
+	
+	
+	<dependencies>
+		<dependency>
+			<groupId>com.github.warmuuh.milkman</groupId>
+			<artifactId>milkman</artifactId>
+			<version>...</version>
+			<scope>provided</scope>
+		</dependency>
+		<!-- and for refering to plugins of milkman: -->
+		<dependency> 
+			<groupId>com.github.warmuuh.milkman</groupId> 
+			<artifactId>milkman-rest</artifactId> 
+			<version>...</version> 
+			<scope>provided</scope>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<!-- for packaging all your dependencies into one jar, excluding provided ones -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-assembly-plugin</artifactId>
+				<version>2.6</version>
+				<configuration>
+					<descriptorRefs>
+						<descriptorRef>jar-with-dependencies</descriptorRef>
+					</descriptorRefs>
+					<appendAssemblyId>false</appendAssemblyId>
+				</configuration>
+				<executions>
+					<execution>
+						<id>assemble-all</id>
+						<phase>package</phase>
+						<goals>
+							<goal>single</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+	
+	
+	<repositories>
+		<repository>
+			<id>jitpack.io</id>
+			<url>https://jitpack.io</url>
+		</repository>
+	</repositories>
+
+</project>
+
    + + + +
    + + +
    +
    +
    + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/docs/features/index.html b/docs/docs/features/index.html index 91e30c6..54b669c 100644 --- a/docs/docs/features/index.html +++ b/docs/docs/features/index.html @@ -120,7 +120,16 @@
  • Documentation
      -
    • +
    • + Developing Plugins + +
    • Features
      • diff --git a/docs/docs/features/slack/index.html b/docs/docs/features/slack/index.html index 12541a8..287cac2 100644 --- a/docs/docs/features/slack/index.html +++ b/docs/docs/features/slack/index.html @@ -123,7 +123,16 @@
      • Documentation
          -
        • +
        • + Developing Plugins + +
        • Features
          • diff --git a/docs/docs/index.html b/docs/docs/index.html index 178c1f9..5075040 100644 --- a/docs/docs/index.html +++ b/docs/docs/index.html @@ -127,7 +127,16 @@
          • Documentation
              -
            • +
            • + Developing Plugins + +
            • Features
              • @@ -322,7 +331,7 @@

                Features

              • JavaFX Application: as in: fast (compared to electron at least :D) and skinn-able (you can extend milkman with your own themes using simple CSS).
              • Commandline Interface: there is a command line interface for Milkman which allows to edit/execute requests on your command line.
              • Slack Command: you can use /milkman <privatebin-url> in slack to share requests in a better way. More Info.
                • -
              • Some more details of the core application features, such as hotkeys etc.
                • +
              • Some more details of the core application features, such as hotkeys etc.

              Existing Plugins:

              Note: see respective plugin folder for more details

              @@ -412,6 +421,14 @@

              Changes

              +
              +
              + Milkman Plugin Development +
              +

              +
              + +
              Advanced Features diff --git a/docs/docs/index.xml b/docs/docs/index.xml index 7c2c378..b14b54c 100644 --- a/docs/docs/index.xml +++ b/docs/docs/index.xml @@ -399,6 +399,64 @@ Example of the Rest plugin + + Docs: Internal Model + https://milkman.dev/docs/development/model/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://milkman.dev/docs/development/model/ + + + + <p>Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.</p> +<h1 id="getting-started">Getting Started</h1> +<p>A <a href="https://github.com/warmuuh/milkman/tree/master/milkman-note">sample plugin</a> was created that shows how to add an Aspect Tab to a Request.</p> +<p>if you want to setup a new project, an exemplary pom can be found <a href="https://milkman.dev/docs/development/setup">here</a>.</p> +<h1 id="data-model">Data Model</h1> +<p><img src="http://www.gravizo.com/svg?@startuml;object%20Workspace;object%20Environment;Environment%20:%20isGlobal;Workspace%20o--%20%22*%22%20Environment;object%20Collection;Workspace%20o--%20%22*%22%20Collection;object%20Request;Collection%20o--%20%22*%22%20Request;%20Request%20--%3E%20HtmlRequest%20;%20Request%20--%3E%20SqlRequest%20;Request%20o-%20%22*%22%20RequestAspect;RequestAspect%20--%3E%20HttpHeaderRequestAspect;RequestAspect%20--%3E%20HttpBodyRequestAspect;@enduml" alt="img"></p> +<p>The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. +A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method.</p> +<p>A request can also contain several <code>RequestAspects</code> which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes.</p> +<p>All Aspects and the container gets serialized using Jackson and stored in a local Database.</p> +<h1 id="extension-points">Extension Points</h1> +<p>Milkman uses <a href="https://docs.oracle.com/javase/tutorial/ext/basics/spi.html">SPI</a> for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the <code>/plugin</code> folder to have milkman pick up your plugin.</p> +<h2 id="requestaspectsplugin">RequestAspectsPlugin</h2> +<p>A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect).</p> +<h2 id="contenttypeplugin">ContentTypePlugin</h2> +<p>A content type plugin is used to format and highlight content based on a mime-type.</p> +<h2 id="requesttypeplugin">RequestTypePlugin</h2> +<p>A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. +This plugin has to provide a small editor for basic attributes of the request as well.</p> +<h2 id="importerplugin">ImporterPlugin</h2> +<p>a plugin that imports things into the current workspace, such as collections, requests, environments.</p> +<h2 id="optionpageprovider">OptionPageProvider</h2> +<p>a plugin to provide a UI for editing options of a &ldquo;logical&rdquo; plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database.</p> +<h2 id="ui-theme-plugin">UI Theme Plugin</h2> +<p>provides an application-theme css and a syntax-theme css for styling.</p> +<h2 id="workspace-synchronizer-plugin">Workspace Synchronizer Plugin</h2> +<p>provides a mechanism to synchronize the workspace with some external mechanism</p> +<h2 id="request-export-plugin">Request Export Plugin</h2> +<p>extension point for adding export methods to a request-type.</p> +<h2 id="collection-export-plugin">Collection Export Plugin</h2> +<p>extension point for adding export methods to a collection.</p> +<h1 id="persistence">Persistence</h1> +<p>All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize.</p> +<h1 id="common-components">Common Components</h1> +<p>Some common components are provided by milkman to make development of plugins easier:</p> +<ul> +<li>TableEditor: a table that might or might not be editable. used for editing headers or environments or such.</li> +<li>ContentEditor: a content editor that supports highlighting and formatting</li> +<li>Dialogs: some common dialogs, such as credentialsInput or StringInput.</li> +</ul> +<h1 id="testing">Testing</h1> +<p>milkman uses TestFX for testing. A <a href="https://github.com/warmuuh/milkman/blob/master/milkman-note/src/test/java/milkman/plugin/note/NotesAspectEditorTest.java">sample test</a> can be seen in the notes plugin.</p> +<h1 id="gotchas">Gotchas</h1> +<p>JavaFX uses a lot of weak references. That means, if you don&rsquo;t keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don&rsquo;t work. +You can use <code>setUserData</code> in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time.</p> + + + + Docs: Milkman Note Plugin https://milkman.dev/docs/plugins/note/ @@ -574,6 +632,81 @@ Example of the Scripting plugin + + Docs: Development Setup + https://milkman.dev/docs/development/setup/ + Mon, 01 Jan 0001 00:00:00 +0000 + + https://milkman.dev/docs/development/setup/ + + + + <p>for creating a new plugin, you can use following pom:</p> +<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">&lt;project</span> <span style="color:#c4a000">xmlns=</span><span style="color:#4e9a06">&#34;http://maven.apache.org/POM/4.0.0&#34;</span> +</span></span><span style="display:flex;"><span> <span style="color:#c4a000">xmlns:xsi=</span><span style="color:#4e9a06">&#34;http://www.w3.org/2001/XMLSchema-instance&#34;</span> +</span></span><span style="display:flex;"><span> <span style="color:#c4a000">xsi:schemaLocation=</span><span style="color:#4e9a06">&#34;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&#34;</span><span style="color:#204a87;font-weight:bold">&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;modelVersion&gt;</span>4.0.0<span style="color:#204a87;font-weight:bold">&lt;/modelVersion&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;dependencies&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>com.github.warmuuh.milkman<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>milkman<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;scope&gt;</span>provided<span style="color:#204a87;font-weight:bold">&lt;/scope&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#8f5902;font-style:italic">&lt;!-- and for refering to plugins of milkman: --&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>com.github.warmuuh.milkman<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>milkman-rest<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>...<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;scope&gt;</span>provided<span style="color:#204a87;font-weight:bold">&lt;/scope&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/dependency&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/dependencies&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;build&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;plugins&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#8f5902;font-style:italic">&lt;!-- for packaging all your dependencies into one jar, excluding provided ones --&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;plugin&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;groupId&gt;</span>org.apache.maven.plugins<span style="color:#204a87;font-weight:bold">&lt;/groupId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;artifactId&gt;</span>maven-assembly-plugin<span style="color:#204a87;font-weight:bold">&lt;/artifactId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;version&gt;</span>2.6<span style="color:#204a87;font-weight:bold">&lt;/version&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;configuration&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;descriptorRefs&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;descriptorRef&gt;</span>jar-with-dependencies<span style="color:#204a87;font-weight:bold">&lt;/descriptorRef&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/descriptorRefs&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;appendAssemblyId&gt;</span>false<span style="color:#204a87;font-weight:bold">&lt;/appendAssemblyId&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/configuration&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;executions&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;execution&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;id&gt;</span>assemble-all<span style="color:#204a87;font-weight:bold">&lt;/id&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;phase&gt;</span>package<span style="color:#204a87;font-weight:bold">&lt;/phase&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;goals&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;goal&gt;</span>single<span style="color:#204a87;font-weight:bold">&lt;/goal&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/goals&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/execution&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/executions&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/plugin&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/plugins&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/build&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;repositories&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;repository&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;id&gt;</span>jitpack.io<span style="color:#204a87;font-weight:bold">&lt;/id&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;url&gt;</span>https://jitpack.io<span style="color:#204a87;font-weight:bold">&lt;/url&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/repository&gt;</span> +</span></span><span style="display:flex;"><span> <span style="color:#204a87;font-weight:bold">&lt;/repositories&gt;</span> +</span></span><span style="display:flex;"><span> +</span></span><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">&lt;/project&gt;</span> +</span></span></code></pre></div> + + + Docs: Slack Integration https://milkman.dev/docs/features/slack/ diff --git a/docs/docs/plugins/authentication/index.html b/docs/docs/plugins/authentication/index.html index 6a928a1..7ae6ab3 100644 --- a/docs/docs/plugins/authentication/index.html +++ b/docs/docs/plugins/authentication/index.html @@ -123,7 +123,16 @@
            • Documentation
                -
              • +
              • + Developing Plugins + +
              • Features
                • diff --git a/docs/docs/plugins/cassandra/index.html b/docs/docs/plugins/cassandra/index.html index 2a6ea56..60d8c9a 100644 --- a/docs/docs/plugins/cassandra/index.html +++ b/docs/docs/plugins/cassandra/index.html @@ -123,7 +123,16 @@
                • Documentation
                    -
                  • +
                  • + Developing Plugins + +
                  • Features
                    • diff --git a/docs/docs/plugins/cli/index.html b/docs/docs/plugins/cli/index.html index 159d87d..4ccbc7c 100644 --- a/docs/docs/plugins/cli/index.html +++ b/docs/docs/plugins/cli/index.html @@ -123,7 +123,16 @@
                    • Documentation
                        -
                      • +
                      • + Developing Plugins + +
                      • Features
                        • diff --git a/docs/docs/plugins/explore/index.html b/docs/docs/plugins/explore/index.html index 3b60a9e..9aeeba5 100644 --- a/docs/docs/plugins/explore/index.html +++ b/docs/docs/plugins/explore/index.html @@ -123,7 +123,16 @@
                        • Documentation
                            -
                          • +
                          • + Developing Plugins + +
                          • Features
                            • diff --git a/docs/docs/plugins/graphql/index.html b/docs/docs/plugins/graphql/index.html index d789acc..801c1ba 100644 --- a/docs/docs/plugins/graphql/index.html +++ b/docs/docs/plugins/graphql/index.html @@ -123,7 +123,16 @@
                            • Documentation
                                -
                              • +
                              • + Developing Plugins + +
                              • Features
                                • diff --git a/docs/docs/plugins/grpc/index.html b/docs/docs/plugins/grpc/index.html index 1fa822f..37a1b5b 100644 --- a/docs/docs/plugins/grpc/index.html +++ b/docs/docs/plugins/grpc/index.html @@ -123,7 +123,16 @@
                                • Documentation
                                    -
                                  • +
                                  • + Developing Plugins + +
                                  • Features
                                    • diff --git a/docs/docs/plugins/index.html b/docs/docs/plugins/index.html index 33cc030..47e554c 100644 --- a/docs/docs/plugins/index.html +++ b/docs/docs/plugins/index.html @@ -127,7 +127,16 @@
                                    • Documentation
                                        -
                                      • +
                                      • + Developing Plugins + +
                                      • Features
                                        • diff --git a/docs/docs/plugins/jdbc/index.html b/docs/docs/plugins/jdbc/index.html index 081d825..7e49552 100644 --- a/docs/docs/plugins/jdbc/index.html +++ b/docs/docs/plugins/jdbc/index.html @@ -123,7 +123,16 @@
                                        • Documentation
                                            -
                                          • +
                                          • + Developing Plugins + +
                                          • Features
                                            • diff --git a/docs/docs/plugins/note/index.html b/docs/docs/plugins/note/index.html index 1a06e30..2621757 100644 --- a/docs/docs/plugins/note/index.html +++ b/docs/docs/plugins/note/index.html @@ -123,7 +123,16 @@
                                            • Documentation
                                                -
                                              • +
                                              • + Developing Plugins + +
                                              • Features
                                                • diff --git a/docs/docs/plugins/privatebin/index.html b/docs/docs/plugins/privatebin/index.html index 8b1376b..e0ea481 100644 --- a/docs/docs/plugins/privatebin/index.html +++ b/docs/docs/plugins/privatebin/index.html @@ -123,7 +123,16 @@
                                                • Documentation
                                                    -
                                                  • +
                                                  • + Developing Plugins + +
                                                  • Features
                                                    • diff --git a/docs/docs/plugins/rest/index.html b/docs/docs/plugins/rest/index.html index 6c3c815..d4f80bf 100644 --- a/docs/docs/plugins/rest/index.html +++ b/docs/docs/plugins/rest/index.html @@ -123,7 +123,16 @@
                                                    • Documentation
                                                        -
                                                      • +
                                                      • + Developing Plugins + +
                                                      • Features
                                                        • diff --git a/docs/docs/plugins/scripting/index.html b/docs/docs/plugins/scripting/index.html index 5e936ae..2f1505e 100644 --- a/docs/docs/plugins/scripting/index.html +++ b/docs/docs/plugins/scripting/index.html @@ -123,7 +123,16 @@
                                                        • Documentation
                                                            -
                                                          • +
                                                          • + Developing Plugins + +
                                                          • Features
                                                            • diff --git a/docs/docs/plugins/sio/index.html b/docs/docs/plugins/sio/index.html index 3af989a..aeb94f4 100644 --- a/docs/docs/plugins/sio/index.html +++ b/docs/docs/plugins/sio/index.html @@ -123,7 +123,16 @@
                                                            • Documentation
                                                                -
                                                              • +
                                                              • + Developing Plugins + +
                                                              • Features
                                                                • diff --git a/docs/docs/plugins/sync-git/index.html b/docs/docs/plugins/sync-git/index.html index 1b97bb2..b64c359 100644 --- a/docs/docs/plugins/sync-git/index.html +++ b/docs/docs/plugins/sync-git/index.html @@ -123,7 +123,16 @@
                                                                • Documentation
                                                                    -
                                                                  • +
                                                                  • + Developing Plugins + +
                                                                  • Features
                                                                    • diff --git a/docs/docs/plugins/test/index.html b/docs/docs/plugins/test/index.html index 08f8fc5..fb4a6bc 100644 --- a/docs/docs/plugins/test/index.html +++ b/docs/docs/plugins/test/index.html @@ -123,7 +123,16 @@
                                                                    • Documentation
                                                                        -
                                                                      • +
                                                                      • + Developing Plugins + +
                                                                      • Features
                                                                        • diff --git a/docs/docs/plugins/ws/index.html b/docs/docs/plugins/ws/index.html index c795772..3cf20f0 100644 --- a/docs/docs/plugins/ws/index.html +++ b/docs/docs/plugins/ws/index.html @@ -123,7 +123,16 @@
                                                                        • Documentation
                                                                            -
                                                                          • +
                                                                          • + Developing Plugins + +
                                                                          • Features
                                                                            • diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 81cc42f..dda49e2 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -39,6 +39,8 @@ https://milkman.dev/community/ 2022-06-16T11:35:31+02:00 + + https://milkman.dev/docs/development/ https://milkman.dev/docs/plugins/explore/ 2022-06-24T16:13:57+02:00 @@ -54,6 +56,8 @@ https://milkman.dev/docs/plugins/rest/ 2022-07-14T14:37:20+02:00 + + https://milkman.dev/docs/development/model/ https://milkman.dev/ 2022-07-14T15:05:37+02:00 @@ -72,6 +76,8 @@ https://milkman.dev/search/ 2022-06-16T11:35:31+02:00 + + https://milkman.dev/docs/development/setup/ https://milkman.dev/docs/features/slack/ 2022-07-14T14:49:16+02:00