Skip to content

Commit 30e54f2

Browse files
author
Peter Mucha
committed
add dev intro
1 parent 78d26f4 commit 30e54f2

File tree

31 files changed

+2679
-58
lines changed

31 files changed

+2679
-58
lines changed

‎content/en/docs/Development/_index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
2+
---
3+
title: "Milkman Plugin Development"
4+
linkTitle: "Developing Plugins"
5+
---
6+
7+
{{% pageinfo %}}
8+
This section shows some information on how to develop your own plugins for milkman
9+
{{% /pageinfo %}}
10+

‎content/en/docs/Development/model.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "Internal Model"
3+
linkTitle: "Internal Model"
4+
description: "Description of domain model of milkman"
5+
6+
---
7+
8+
Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.
9+
10+
# Getting Started
11+
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.
12+
13+
if you want to setup a new project, an exemplary pom can be found [here](/docs/development/setup).
14+
15+
# Data Model
16+
17+
![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)
18+
19+
The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests.
20+
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.
21+
22+
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.
23+
24+
All Aspects and the container gets serialized using Jackson and stored in a local Database.
25+
26+
# Extension Points
27+
28+
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.
29+
30+
## RequestAspectsPlugin
31+
32+
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).
33+
34+
## ContentTypePlugin
35+
36+
A content type plugin is used to format and highlight content based on a mime-type.
37+
38+
## RequestTypePlugin
39+
40+
A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of.
41+
This plugin has to provide a small editor for basic attributes of the request as well.
42+
43+
## ImporterPlugin
44+
45+
a plugin that imports things into the current workspace, such as collections, requests, environments.
46+
47+
## OptionPageProvider
48+
49+
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.
50+
51+
## UI Theme Plugin
52+
53+
provides an application-theme css and a syntax-theme css for styling.
54+
55+
## Workspace Synchronizer Plugin
56+
57+
provides a mechanism to synchronize the workspace with some external mechanism
58+
59+
## Request Export Plugin
60+
61+
extension point for adding export methods to a request-type.
62+
63+
## Collection Export Plugin
64+
65+
extension point for adding export methods to a collection.
66+
67+
# Persistence
68+
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.
69+
70+
# Common Components
71+
Some common components are provided by milkman to make development of plugins easier:
72+
73+
* TableEditor: a table that might or might not be editable. used for editing headers or environments or such.
74+
* ContentEditor: a content editor that supports highlighting and formatting
75+
* Dialogs: some common dialogs, such as credentialsInput or StringInput.
76+
77+
# Testing
78+
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.
79+
80+
# Gotchas
81+
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.
82+
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.

‎content/en/docs/Development/setup.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: "Development Setup"
3+
linkTitle: "Setup"
4+
description: "Description of how to setup your environment"
5+
---
6+
7+
for creating a new plugin, you can use following pom:
8+
9+
10+
11+
```xml
12+
<project xmlns="http://maven.apache.org/POM/4.0.0"
13+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
14+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
15+
<modelVersion>4.0.0</modelVersion>
16+
17+
<groupId>...</groupId>
18+
<artifactId>...</artifactId>
19+
<version>...</version>
20+
21+
22+
<dependencies>
23+
<dependency>
24+
<groupId>com.github.warmuuh.milkman</groupId>
25+
<artifactId>milkman</artifactId>
26+
<version>...</version>
27+
<scope>provided</scope>
28+
</dependency>
29+
<!-- and for refering to plugins of milkman: -->
30+
<dependency>
31+
<groupId>com.github.warmuuh.milkman</groupId>
32+
<artifactId>milkman-rest</artifactId>
33+
<version>...</version>
34+
<scope>provided</scope>
35+
</dependency>
36+
</dependencies>
37+
38+
<build>
39+
<plugins>
40+
<!-- for packaging all your dependencies into one jar, excluding provided ones -->
41+
<plugin>
42+
<groupId>org.apache.maven.plugins</groupId>
43+
<artifactId>maven-assembly-plugin</artifactId>
44+
<version>2.6</version>
45+
<configuration>
46+
<descriptorRefs>
47+
<descriptorRef>jar-with-dependencies</descriptorRef>
48+
</descriptorRefs>
49+
<appendAssemblyId>false</appendAssemblyId>
50+
</configuration>
51+
<executions>
52+
<execution>
53+
<id>assemble-all</id>
54+
<phase>package</phase>
55+
<goals>
56+
<goal>single</goal>
57+
</goals>
58+
</execution>
59+
</executions>
60+
</plugin>
61+
</plugins>
62+
</build>
63+
64+
65+
<repositories>
66+
<repository>
67+
<id>jitpack.io</id>
68+
<url>https://jitpack.io</url>
69+
</repository>
70+
</repositories>
71+
72+
</project>
73+
```

‎content/en/docs/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ some resolved issues and FAQs are available in the [wiki](https://github.com/war
5858
* **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).
5959
* **Commandline Interface:** there is a [command line interface](plugins/cli) for Milkman which allows to edit/execute requests on your command line.
6060
* **Slack Command:** you can use `/milkman <privatebin-url>` in slack to share requests in a better way. [More Info](features/slack).
61-
* [Some more details](docs/features.md) of the core application features, such as hotkeys etc.
61+
* [Some more details](features/) of the core application features, such as hotkeys etc.
6262

6363
# Existing Plugins:
6464

0 commit comments

Comments
 (0)