Xd-dialog-helper (a helper library to make dealing with dialogs easy)

Adobe XD UXP Plugin API
, ,
21

Known issue / what you should know when using the library

Please note that it is currently not possible to consistently set the value (i.e., content) of a <textarea> across platforms inside dialogs of plugins for Adobe XD. Therefore, this currently also doesn’t work consistently in the library (it will work fine on Windows, but won’t set a value on macOS).

Please refer to How to set textarea value when not added or just added to the document for more details.

As soon as this is fixed (either by my library or by Adobe), I’ll also write about it here.

1 Like
22

v1.0.0 Beta 0

Exciting news: after reaching 100 % coverage with my unit tests (no better feeling than that after spending two days writing tests), I’ve just released the first Beta of version 1.0 of xd-dialog-helper.

You can obtain it from the release page or by running

npm install xd-dialog-helper@next

There should be almost no breaking changes with the Beta, although you’ll need to do some minor changes (shouldn’t take more than 5 minutes) for the actual release (certain aspects got moved and are still available via the old way, but marked as deprecated, during the beta and will get removed in the final release).

To learn how to migrate, please take a look at the migration guide in the release notes or the README.

Please note: As of yet, the WYSIWYG dialog creator / editor at https://xd-dialog-helper.pabloklaschka.de/ isn’t compatible with the new version. That will be my project for this weekend, meaning we’ll hopefully be able to use it for the new version early next week :tada:

Some reasons why you should migrate

  • v1.0 of course means that this is the first stable version. As mentioned before, I now have 100% coverage on the unit tests and a lot more QA for new releases, meaning you can feel safe and simply enjoy using the library :sunglasses:
  • Support for custom types. I can’t stress this enough: this is HUGE. Everyones now able to add custom types (relatively easily) for the library. Furthermore, I’ll (and hopefully others as well will) release content types which I find useful that don’t belong into the “core” library, meaning a big selection of components that that you can use in your dialogs as easily as any “standard” components from the library
  • Child elements. Especially in conjunction with custom elements, this could be pretty cool as well. This adds support for collapsable sections, tabs, multi-step-plugins and much more (whatever you can imagine).
  • Typescript support thanks to typescript definitions including doc comments etc.
  • more stability
  • more features
  • …

Suffice it to say: the enhancements out-weigh the minimal effort of changing dialogHelper.CHECKBOX to dialogHelper.types.CHECKBOX, which really should be the only breaking change…

1 Like
23

Nice work!

Any reason this won’t work with panel plugins?

1 Like
24

@cpryland

Thanks :slightly_smiling_face:.

Unfortunately, it won’t work for panels (for now), since the it’s optimized to have a simple syntax for displaying dialogs (which ask users for an input in a form-like input style).

I am, however, planning to port this to panels so that the same components and easy-to-use input parsing (the library “hands” you user input as a key-value-pair object) can get used for that as well. As I am, however, currently in the middle of exams, writing all the docs for the new dialog version, releasing a new plugin (hopefully in the next few days/weeks) and more, that might still take a while to become a reality…

In general, however, I do believe that for the kind of input the library is optimized for, dialogs will still be the way to go (which is also, why I, for example, won’t port my Lorem Ipsum plugin to a panel. For it, a modal simply is the better workflow).

25

It’s official. Version v1.0.0, the first officially stable version (with 100 % unit test coverage and many more QA features) is officially released.

Documentation has now moved to https://xd-dialog-helper.pabloklaschka.de. New features include new validation options, full support for UXP 3 and many more (e.g., custom elements and so on).

Migration also is incredibly easy. For more details, see the migration section below :wink:

@ashryan As per Add to XD-Awesome · Issue #19 · pklaschka/xd-dialog-helper · GitHub, I’ll also create a PR for xd-awesome later today :slightly_smiling_face:

Documenation for the library has therefore moved to a different repo (GitHub - pklaschka/xd-dialog-helper-docs: Docuementation for the xd-dialog-helper library), which I’ll turn public later today. Also, the WYSIWYG editor (now at https://xd-dialog-helper.pabloklaschka.de/editor/) is now done using React and much more easy to update, and includes a new feature to let you download the JS file for the created dialog, making incorporating created dialogs in your project quicker and easier than ever. As also my Lorem Ipsum plugin got ported to use the library (update will get released in a few days), I’ve included a “real-world” example including localization and retaining input values in the docs with the “real” code of the plugin :wink:.

Migration guide from pre-v1.0.0 versions

Mostly, there should be no breaking changes (but many additional options and improvements) in v1.0, since it mostly consists of an internal restructuring.

However, with the release of the new version, the types have moved to a types namespace inside the xd-dialog-helper module.

This means that instead of writing

dialogHelper.showDialog('dialog', 'My dialog', [{
    id: 123,
    type: dialogHelper.TEXT_INPUT,
    label: 'Good morning'
}]);

we have to write:

dialogHelper.showDialog('dialog', 'My dialog', [{
    id: 123,
    type: dialogHelper.types.TEXT_INPUT,
    label: 'Good morning'
}]);

Also, the type constant previously were aliases for numeric constants representing the type. This is no longer the case (to support custom types), which is why numeric values are no longer possible for the type field.

1 Like
26

This is exciting news Pablo!

Where on here can I find the docs?

1 Like
27

@ashryan

https://xd-dialog-helper.pabloklaschka.de/docs/installation.html

image
image1354×642 39.2 KB

Accessible via the CTA Read the docs or the menu item Docs :wink: (it might be that you’re still seeing the old WYSIWYG editor under the URL. That would be due to caching, as the editor worked as PWA. Restarting the browser or similar actions should hopefully help, otherwise try appending some random query string to the url like ?v=2…)

(it should be mentioned that I am anything but a good technical writer, so any suggestions are more than welcome in the docs repo, GitHub - pklaschka/xd-dialog-helper-docs: Docuementation for the xd-dialog-helper library)

2 Likes
28

Hi @pklaschka, this helper looks very useful! Is it now compatible with panel ui plugins? (ie, I click a button in the panel and I want a dialog to appear) Thanks so much. I’m trying to create my own dialog within a panel ui but the form inputs are not cleared correctly when the dialog gets closed.

1 Like
29

High-level aside: this is most likely because you are leaving the dialog attached to the DOM and reusing it on each plugin invoke. In other words, you’re simply “hiding” and “showing” the DOM element, which won’t clear it.

In that case, your options would be either:

  1. Remove the DOM element on dialog close, and reattach it each time the plugin is run
  2. Create a method for clearing all form inputs on dialog close

Either way could be valid depending what your plugin does.

30

Hi @qmulus,

Thank you for your message and kind words. Unfortunately, for now, you won’t be able to use the library in conjunction with panels as I clear the document’s body contents in the library (an artifact from before panels were a thing :slightly_smiling_face:). I have however noted your request and will hopefully get to make it compatible in the somewhat near future (I currently have an awful lot of stuff to do, meaning I won’t make any promises about any ETAs since I would fail such a target miserably, but I have noted this request and it will be part of the next update, whenever that will be :wink:).

Best,
Pablo