Adobe UXP: Things you need to know! #2 Documentation

In this episode I’m covering adobe.io, the new developer portal that hosts the Photoshop UXP documentation among other things. And for once I’m glad they’re stealing my job – the material they’ve put together does stand out!

If you find this content useful, please consider supporting me – 2020 is a hell of a year. I don’t have a Patreon page, but I’ve got two fairly cheap plugins on the Photoshop Marketplace, ALCE (Advanced Local Contrast Enhancer) and Double USM (on sharpening). If you happen to buy them, please leave a positive rating/review, it would greatly help. Or, you can

If you cannot, or don’t want to, that’s OK anyway.
Stay safe and thanks! 🙏🏻

The whole series so far

Transcription

The transcripted video looks weird, but I’m told it helps to have it anyway because it’s easier to translate to other languages. Apologies for the lack of punctuation and the sloppy syntax.

Hey I’m Davide and this is Adobe UXP: Things you need to know! Today I’m talking about documentation. And I know this doesn’t really sound exciting, and a lot of you have already asked me to cover more advanced topics such as BatchPlay or the Alchemist plugin but this series tries to reach a larger audience, even people who have less experience in Adobe development. Hence learning how to navigate the new documentation portal is paramount; and by the way Adobe has put a lot of effort in the creation of such documentation so it’s fair for us at least to acknowledge their efforts and try to understand what’s in there. And by the way the UXP section of the Adobe portal for developers is a work-in-progress so let’s be forgiving if we find a link that is missing, or information that is a bit rough. So let me show you what we’re talking about. So this is the place to go Adobe.io and you might be tempted to just scroll down until you find the Adobe Photoshop API and click learn more. This is not really what you would expect if you’re looking for UXP content because the Photoshop API is something related to Photoshop as a Service, which is not the Photoshop-server thing but closer to it than it is to UXP. Quite interesting one, but not what we are after. You have to click this discover tab here and then you can find Photoshop, and here, right about here the UXP plugin API mini-site. so let’s click “View the docs” and here it is. This is the landing page with information on what to expect in this mini-site and let me pick the Guides and first thing that pops to the eye is that we have three levels of Navbars. So the top navbar here is the first level, and we have selected the Guides, and the second level is on the sidebar at the left, and the sidebar on the right just keeps track of where we are in the page as we scroll down or up. Other thing to notice is this “Edit in GitHub” link here and “Log an issue” because all this website, which by the way is based on something called the Gatsby Theme Parliament, Adobe Gatsby Theme Parliament or something like that, this is a template that uses Gatsby hence React.js that Adobe has made open source and you can look for it if you want. So everything here belongs to this AdobeDocs user, and this UXP-Photoshop repository also you can log an issue here if you find, I don’t know what, misleading information, or wrong statements or missing links, or whatnot. Again this is a working progress so it is to be expected to find missing pages and wrong links; that’s going to be okay. So I’m going to quickly browse through the documentation – not reading it, but just pointing out interesting elements so that you know where to find them when you will need it in the future. So the “Getting Started” is just a very quick overview of the UXP technology and “UXP for you” points you to different pages depending on your background so if you are a UXP developer in XD but not in Photoshop you start here, if you have CEP experience but not UXP then you go there and, so on and so forth. “UXP toolchain” is describing you what you need in case you want to use, you want to create UXP plugins vanilla javascript UXP plugin so the UXP developer tool and then Visual Studio Code, a code editor or a more advanced toolchain in case you want to create React based UXP plug-ins so Node.js, npm and so on and so forth, how to install them and and other other things. So for instance this Kitchen-Sink example here is a sample plug-in that shows all the elements that you can use in the interface. Quite useful. “UXP for Photoshop basics” well this is the DOM, or the scripting side of UXP in Photoshop, so they tell you synchronous versus asynchronous scripting, how to use the various objects that are provided in this required Photoshop object. So in the app you have documents layer and so on and so forth, so this is just scripting. The “UXP Developer Tool” is a brief section or introduction to it, more information in the “Developer Tool walkthrough” where they tell you how to watch, load, reload, create a new plugin from a template and so on and so forth. And in “Other topics” you can find info about the UXP manifest, how to localize your plugin, the flyout menu access, file system, networking and Spectrum CSS. So what else? “How do I…” this is a section that tells you how to perform basic tasks, so for instance: exporting and importing modules in your UXP plugin, how to use promises, async awaits. Specific snippets, these are things that you might find yourself using over and over again, especially for debugging purposes. FileIO, or other useful snippets, this shows you how to display a simple alert and mind you there is no equivalent in UXP to the prompt or the confirm functions, at least so far. Theme awareness: this goes into a theming for the plugin, and CSS vars so you can use –UXP-host-background-color so on and so forth. You also have examples on how to use them. Debugging your plugins shows you how to look for manifest problems, installation problems, javascript, CSS and what else, especially Gremlins. We have a lot of Gremlins in UXP. Photoshop API this is a section where you dig deeper into the scripting side of UXP, so you have all these modules for all the various objects that you have in the Photoshop: apps, action, action set, document, layer, and so on so forth. So let me just bring up the layer where you have all the various props and functions that you can run. So for instance how to duplicate a layer, right, and this is the place where to find all information. Mind you the DOM is still largely incomplete, so it is okay if you don’t find here what you were looking for, because you can always use BatchPlay which is here and this is the section where they tell you about the various BatchPlay options and how to run it. It’s quite bare as a section but I’m sure they’re going to add more information as time goes by. API extensions this is something I doubt I have already covered in my previous video and it’s interesting. I want to mention it here. We are now allowed to extend the prototype of a native object so you can add this custom prepend low-dash for instance function in the document prototype so that you can call it, for instance app.activedocument then you can run this prepend low dash that is going to rename all the layers prepending a low dash in their name so you can extend the prototype of the Photoshop document, layer, action set, and action. Then there’s this section about the communication between a UXP plugin and C++ plugins and how to listen to events. Also here they mentioned that app event notifier is not something that you want to use in commercial plugins because this is quite resource intensive and by the way it requires for the user to have the developer mode switched on in the Photoshop preferences, which users usually don’t have. So this is okay when developing a UXP plugins, this is not okay when these plugins are shipped to the marketplace. UXP API this is a section about instead the specific things of UXP, so not the host application, not Photoshop, not the scripting, but the panels and stuff. The javascript reference, global members, and modules these are all the things that you have access to in UXP so the clipboard websocket fetch and what else: data storage, you have local storage and a session based storage and all the various html events, html dom, and html elements, and the modules. These are specific to UXP so you have the “os” not to be confused to node.js “os” this is a different thing, you have three different methods for the platform: darwin is Mac, or windows-whatever is Windows. The release number, and then the architecture: 32-bit 64 and so on so forth. Mind you the release doesn’t correspond to the actual macOS version if you are on darwin. Let me show that to you: darwin versions, so for instance let me scroll down here if you have a darwin version of I don’t know 18.2 this is macOS 10.14, so you have to match them in order to know what operative system your users are using. Then the shell has just one method which is used to open a url in the default browser and then the ux well this is big I’m not going to cover this here because it’s going to have its own video but these are UXP specific things. For instance the entry points is an object that takes care of what happens during the UXP life cycle for instance the functions that you want to run when the panel shows or is created. And then you have storage, various information about it and key/value storage, version, host information and so on and so forth. The secure storage don’t be misled by the name: secure storage is encrypted but the user can decrypt it so you won’t store here information that you want to hide from the user, so for instance licensing information – this is not the right place. Just mentioning this. And then what we have CSS reference here, so what’s available in UXP in terms of CSS as I mentioned in a previous video not everything is available so you have all the general variables, units, you can also use a “calc” function, which is cool and then what: selectors, media queries, pseudo elements, pseudo classes, and styles. So all these things are available with some caveats: so for instance the opacity here sets the opacity of an element, that’s okay. You have the MDN link but then quirks and exceptions: red flag Photoshop does not support this property although UXP will parse it do not use this style to control visibility! So read all of that if you’re going to use these styles here. And then what else_ we have similarly an html reference with the general supported and unsupported elements. Let’s check the unsupported elements first: in the typography quite surprisingly you don’t have a italic, you don’t have a strong, you don’t have a blockquote, pre, or code, you don’t even have an ordered list nor ordered list. You can add them, they won’t display as you expect them to do so you have to add your own styling for that. You don’t have the title. And these are the unsupported attributes, and then you have all the things that are instead supported: the body, the head, the html, link, so on so forth. Hierarchy, let me pick this h4 here, they tell you that the h4 is equivalent to the Spectrum heading of size extra-small, okay thank you. And then you have this Spectrum UXP reference because you know you can use Spectrum web components, they are already available without the need for you to import anything, as sp-something: sp-button and so on and so forth. So let’s see what’s in there about Spectrum UXP, so what’s Spectrum UXP, and using it with React. React has some quirks in terms not of Spectrum web components but web components in general. For instance, you have to use a closing tag, not self-closing tags. With Spectrum web components you have to use class instead of classname, so if you have a div in React well then you have to use classname, if you have e.g. a Spectrum icon you have to use class. And then more and then this is really important boolean attributes, this which you would normally use with React is not going to work with Spectrum web component: instead you have to use the ternary operator, and check for the property and set explicitly to true or null or undefined. And then event handling. What else: typography here, these are the available Spectrum typography web components and by the way if you look at the Spectrum web components website, this here, you don’t have for instance the sp-body that instead you have available in UXP. So there is an overlap between Spectrum web components in UXP and Spectrum web components tout-court but it’s a funny kind of overlap. And then you have sp-detail, a heading, label and so on and so forth. If you want to see how they look uh well then you have to go to the Spectrum web components website and then you have here for instance the switch which by the way is not one of the available web components in UXP so you have it here you can see how it looks but in this case it’s not found among the UXP components but it will be introduced later on. So if you want to see for instance sp-detail let’s check, detail should be in the typography, probably… no no it turns out that not even sp-detail is found here but it should be found in the Spectrum CSS, so Spectrum CSS we should have the sp-detail I think in the typography here, please, yeah typography detail so you see it’s it’s kind of funny: some things are found in the Spectrum web components, other things are found in the Spectrum CSS, and some of them are in the UXP. Anyways, user interface these are all the available elements such as buttons, checkboxes, and whatnot. Again let me check for instance this here, yeah you have a graphic display of how they look like, not as interactive as the one in the Spectrum web component, so for instance let me check this slider here. These should be functional, yes, these are just images, yes, and then you have uh the code samples down below. Known issues, this is something really important that you should know like the back of your hand because many things won’t work as you would expect them to do, and so here you find all the known issues for UXP right? Sample code you find here javascript samples, React samples, and batch play samples. Then the design section is about designing a plug-in experience, so basically the Adobe guidelines in terms of the UI of the plug-in UX patterns. I don’t think these links work, yes they don’t but they will. So the user experience patterns, the user interface suggestions and so on and so forth. And then a section on the developer tool installation, plugin management, and working with React. And the UXP dev tool. The share tab is quite important as well because here is where Adobe tells you how to package your plugin, that is to say how to create the .ccx file, the options that you have for distribution, so for instance you can email they say your .ccx file, or upload it to the marketplace. The various guidelines for submission and review to the marketplace, and again: this is quite a strict process so you have to follow the Adobe guidelines otherwise your plugin is going to be rejected. And how to market your plugins t– his is not yet there but they’re going to add this kind of information as well. And finally the community: so we have now a Creative Cloud developer forums based on Discourse I think. Actually Adobe XD already had it I think, because this message is from August 2018, if I am correct. I should be. and the Photoshop section has been added quite recently so this is the place where you can meet other developers and discuss topics, and ask questions. Then you have the GitHub repo for the entire UXP doc minisite and the sample code repo where you can find all the available samples. So these are plugins that you can just, you know ,grab the code from and and learn from. WebSocket example, web service call example, and so on and so forth. And I think that with this I can wrap this video up. If you have enjoyed it please consider supporting me I don’t have any Patreon pages as I told you last time but I have Adobe development content and especially if you want to help: a purchase of my two extensions that are in the UXP marketplace would be a great thing, they’re still for sale at 16 bucks each, and if you happen to buy them just please leave a positive rating or review which will help immensely. If you cannot or don’t want to that’s okay right thank you for watching and see you in the next one. Stay safe! Bye.