@momsfriendlydevco/macgyver v2.0.15

MacGyver

Dynamic form widgets for Vue.

MacGyver is a component library and dynamic form designer for Vue.

It can function either as a simple set of powerful independent components or by using a powerful JSON form layout definition.

LIVE DEMO

Prerequisites

This package requires the following as pre-requisite dependencies in the parent:

• @momsfriendlydevco/vue-setpath
• @doop/watch-all
• @doop/emit

These are listed as peerDependencies in package.json.

Example

<mg-form
	:data="{}" // Populated as the control values change
	:config="{ // Our form specification
		type: "mgContainer",
		items: [
			{
				id: "textInput",
				type: "mgText",
				title: "Example Text",
			},
			{
				id: "toggleControl",
				type: "mgToggle",
				default: true,
			},
		],
	}"
	@change="data = $event"
/>

or use MacGyver widgets as standalone Vue components:

<mg-number
	:value="formData.number"
	@change="formData.number = $event"
	:min="0"
	:max="100"
/>

Creating MacGyver widgets

Each MagGyver widget begins with mg and should be registered via Vue.mgComponent(name, definitionObject).

Vue.mgComponent('mgText', {
	meta: {
		title: 'Textbox',
		icon: 'fa fa-pencil-square-o',
	},
	props: {
		placeholder: {type: 'mgText', help: 'Ghost text to display when the textbox has no value'},
	},
}));

The Vue.mgComponent() function processes the MacGyver widget definition and automatically calls Vue.component() to register the Vue counterpart (after converting prop types and adding other syntax glue to the original object).

Widget setup

MacGyver widgets follow the regular Vue component syntax with some additions:

NOTES:

• meta.format returns the human readable value of the component when rendered in tables - if true the value is used unchanged. If a function it is called as (value, config) and can return a scalar string or a Promisable value which should resolve into a string.
• props{}.type should always be a MacGyver component + config so it can be correctly displayed in the editor. Passing JS primative classes (e.g. {foo: Number}) will raise a warning message and is discouraged for anything other than testing
• props{}.advanced can be used to hide more complex properties unless the editor is in advanced editing mode
• props{}.vueType can override the "guessed" type to pass to Vue as a prop validator. Pass strings or arrays of strings not native types - for example {vueType: 'string'} or {vueType: ['array', 'number']} are both correct, {vueType: String} is not supported
• data() is called as per the usual Vue setup process, however the data value is always provided and is watched by MacGyver for changes. Mutate this value to set new values or emit mgChange if needed
• childProps sets up the properties inherited into the $props setup by direct children. Items such as title are used by elements such as mgContainer to render the title of the widget and not the widget itself

Injectables

The following injectables can be subscribed to within each component:

To specify optional injectables (e.g. that $mgFormEditor may be included but is not essencial) use:

{
	inject: {
		$mgForm: {from: '$mgForm', default: false},
		$mgFormEditor: {from: '$mgFormEditor', default: false},
	},
}

NOTES:

• $mgForm is only injected if the component is used inside a <mg-form/> component, otherwise its falsy. This usually occurs when the component is used as a standalone e.g. <mg-button/>
• $mgFormEditor is only injected if the form is wrapped within a editor context, check for its truthy status to determine if the widget should apply editable behaviours

Events

NOTES:

• All of the above events are automatically added by the mgSetup() method when the component is created

Component Skeleton

In essence the following base skeleton is used for any component that is instantiated via Vue.mgComponent(name, spec). This contains all the injectables, default data props, default events and other hooks. This structure can be considered a Vue.mixin() / _.merge() equivalent where all items are deep merged.

Vue.mgComponent('mgAcmeComponent', {
	meta: {
		title: 'mgAcmeComponent',                            // Calculated via _.startCase() from the name
		icon: 'far fa-rectangle-wide',
		category: 'Misc',
		preferId: false,
		shorthand: [],
		format: true,
		formatClass: '',
	},
	inject: {
		$mgForm: {from: '$mgForm', default: false},          // Will be falsy if the component is stand-alone
	},
	props: {
		$dataPath: {type: String},                           // Default is set when component is populated (when inside an mg-form)
		$specPath: {type: String},                           // Default is set when component is popualted (when inside an mg-form)
		value: {},                                           // Default is populated when a stand-alone component
	},
	methods: {
		mgSetup() {                                          // Function which sets up event handlers and data watcher
			// ... //
		},
	},
	created() {
		this.mgSetup();                                      // Called on every create
		// ... //                                            // component created() lifecycle hook is called here
	},
	// ... //                                                    // Remaining component properties, methods and lifecycle hooks
});

API

$macgyver.compileSpec(spec)

Attempt to compile up a 'rough' MacGyver spec into a pristine one. This function performs various sanity checks on nested elements e.g. checking each item has a valid ID and if not adding one. It returns an object composed of the form {spec}

$macgyver.widgets

An object containing data on each valid MacGyver widget registered. If running on the front-end this is updated as new widgets register themselves. On the backend this uses the computed version located in ./dist/widgets.json.