FED-681: Add integration docs

[hunterbreathat-wk]

Motivation

There was a support question on how to properly integrate with the devtools for a module. It appears that these steps don't exist here yet.

Changes

• Add documentation from Devtools

Release Notes

• Introduce DevTools integration documentation

Review

See CONTRIBUTING.md for more details on review types (+1 / QA +1 / +10) and code review process.

Please review:

QA Checklist

• Tests were updated and provide good coverage of the changeset and other affected code
• Manual testing was performed if needed
  • Steps from PR author:
  • Anything falling under manual testing criteria outlined in CONTRIBUTING.md

Merge Checklist

While we perform many automated checks before auto-merging, some manual checks are needed:

• A Frontend Frameworks Design member has reviewed these changes
• There are no unaddressed comments - this check can be automated if reviewers use the "Request Changes" feature
• For release PRs - Version metadata in Rosie comment is correct

[aviary-wf]

Security Insights

No security relevant content was detected by automated scans.

Action Items

• Review PR for security impact; comment "security review required" if needed or unsure
• Verify aviary.yaml coverage of security relevant code

---

Questions or Comments? Reach out on Slack: #support-infosec.

[kealjones-wk]

.... Im second guessing these changes and kinda thinking maybe we just have a simple section that is a bit more to the point...

Integration With DevTools

In order to display the properties of Dart based Actions and State in the DevTools they must implement a toJson method.

toJson can be manually added to the classes, or added with the help of something like the json_serializable package.

State Example:

class FooState {
  bool foo = true;
  
  Map<string, dynamic> toJson() => {'foo': foo};
}

When converted, the result of the toJson will be used to represent the entire state.

{
  "foo": true
}

Action Example:

class FooAction {
  bool foo = false;
  
  Map<string, dynamic> toJson() => {'foo': foo};
}

When converted, the Class name will be the type property and toJson will become the payload property.

{
  "type": "FooAction", 
  "payload": {
    "foo": false
  }
}

For more encoding details check out the redux_remote_devtools package.

[kealjones-wk]

Suggested change

	serializable. This can be implemented manually or with the help of the [json_serializable](https://pub.dev/packages/json_serializable) library.
	serializable. This can be implemented manually via a `toJson` method or with the help of the [json_serializable](https://pub.dev/packages/json_serializable) library.

[kealjones-wk]

Suggested change

In the Javascript world, Redux follows a convention that your redux state is a plain Javascript Object, and actions are also Javascript objects that have a type property. The JS Redux Devtools expect this. However, Redux.dart tries to take advantage of the strong typing available in Dart. To make Redux.dart work with the JS devtools, we need to convert actions and state instances to JSON before sending.

The Redux Devtools anticipate JS Objects. However, because Redux.dart uses Dart's strong typing, which doesn't map 1 to 1 with JS, so in order to see Dart properties in the DevTools, we need to convert the actions and state to JSON. To do this `jsonEncode` is used before sending to the DevTools, it defaults to calling `.toJson()` on the object.

[kealjones-wk]

Suggested change

	We use the class name as the action type for class based actions. For enum typed actions, we use the value of the action. For example:
	The class name automatically gets used as the Action's `type` for class based actions. For enum typed actions, the value of the Action is used. For example:

[kealjones-wk]

Suggested change

	We also want to send the action properties over to devtools. To do this, we attempt to `jsonEncode` the entire Action, and
	attach this JSON data as a payload property. For example:
	To include the Action's properties in the devtools `jsonEncode` is performed, and the resulting JSON is attached as the `payload` property. For example:

[kealjones-wk]

Suggested change

	```json lines
	{
	"type": "ClassAction",
	"payload": {
	"someValue": 5 // or whatever someValue was set to
	},
	}
	```
	```json lines
	{
	"type": "ClassAction",
	"payload": {
	"someValue": "whatever someValue was set to"
	},
	}

[kealjones-wk]

Suggested change

	toJson() => {'someValue': this.someValue};
	toJson() => {'someValue': someValue};

[kealjones-wk]

Suggested change

	Ensure that your `Action` and `State` implement a `toJson` method.
	Ensure that your `Action`s and `State` implement a `toJson` method.

[kealjones-wk]

Suggested change

	[//]: # (___Overriding these strategies___)
	[//]: # ()
	[//]: # (The strategy described above should work for most cases. However, if you want to do something different, you can replace the ActionEncoder and StateEncoder with your own implementations:)
	[//]: # ()
	[//]: # (var remoteDevtools = RemoteDevToolsMiddleware('192.168.1.52:8000', actionEncoder: MyCoolActionEncoder);)

[kealjones-wk]

@greglittlefield-wf could you also take a look at this and see if you have any feedback?

[kealjones-wk]

Suggested change

	Map<String,dynamic> toJson() => {'foo':foo};
	Map<String, dynamic> toJson() => {'foo':foo};

[kealjones-wk]

Maybe we should mention that all values need to be json encodable if a value contains objects that are not directly encodable to JSON (a value that is not a number, boolean, string, null, list or a map with string keys) we will attempt to call toJson on it.

[greglittlefield-wf]

One comment and some nits, otherwise LGTM!

[greglittlefield-wf]

#nit semicolons aren't valid here

Suggested change

	ACTION_2;
	ACTION_2,

[autobot-wf]

Skynet test results failed initially for this build but were approved by greg.littlefield
https://wf-skynet-hrd.appspot.com/apps/test/smithy/4261008/1
Approval message: Failing GH Actions run is unrelated to this PR, and failing in master

[greglittlefield-wf]

+10

[KealJones]

+10

[kealjones-wk]

+10

[greglittlefield-wf]

@Workiva/release-management-p

[rmconsole-wf]

+1 from RM