TypeScript Enabled CEP Development

Report · Dec 06, 2017

[Apologies for cross-posting. I only just became aware that this forum even existed.]

For those interested in a more modern approach to Add-On development, take a look at this post which points to this CEP Sample. In short, it provides an example environment where the Premiere Pro sample "PProPanel" was adapted to benefit from a TypeScript-enabled environment (for both the Panel [HTML] and Application [ExtendScript] contexts).

Further, other Adobe application-specific TypeScript Declaration Files have been created by pqiorpa and can be found here.

One major benefit of working in a TypeScript-enabled environment is that you can use modern IDEs and still gain the benefit of Intellisense/Autocomplete features, whether you're writing pure ExtendScript or TypeScript that you will transpile into ExtendScript!

Happy coding!

Report · Dec 06, 2017

Hey Sberic,

Just want to thank you for the typings you have created, I plan to integrate them into my bundler soon (Adobe Extension Development Tools · GitHub)

I also wanted to show you the following project that has typings for AE, perhaps you can convince him to integrate the typings into your project? (GitHub - atarabi/aftereffects.d.ts)

It would be great to have them all in one place so we can easily contribute to it.

Lastly, I have got PPRO on my system (2018) and I think I have 2017 running in a VM somewhere, I will run your xml -> d.ts script on them soon and make a PR.

Thanks again for your work, TypeScript on Adobe CC is a reality now, yay!!

- Koen

Report · Dec 06, 2017

Hi @vespkoen! No problem! I'm happy to contribute back to the community.

I wasn't previously aware of Atarabi's repository. That's pretty awesome! It looks like we now have three locations for Adobe application Declaration files:

atarabi/aftereffects.d.ts
- After Effects
pravdomil/types-for-adobe
- Audition
- Illustrator (2015.3)
- InDesign (2015.3)
- JavaScript (ECMAScript 3 w/ExtendScript base extensions)
- PhotoShop (2015.5)
- ScriptUI
Adobe-CEP/Samples/TypeScript
- PremierePro (11.1.2)

Unifying these efforts would be excellent, but I honestly believe that we need Adobe support to make it happen properly. Here are the issues that I foresee:

We need a unified way to align declaration file versions to application versions. Adobe occasionally adds/adjusts APIs for applications between application versions. We can't simply have a single Declaration file for "Audition" because CC2018 may have different APIs available than CC2017 did. Perhaps the NodeJS declaration files would make for a good model here...
Not all APIs for all applications are covered by Adobe's XML documentation. The ESTK Object Model Viewer seems to source its API documentation from XML files and some direct connection to the application you're investigating - it seems to discover APIs (see, for example, Premiere Pro). Even then, not all APIs will appear in the ESTK OMV. The APIs found in the Premiere Pro declaration file were sourced from the api_doc.html, the ESTK OMV, and direct conversation with Bruce Bullis. The point is that straightforward XML→Declaration file conversion will only take you so far; you'll likely miss some things.

My efforts to get Adobe buy-in on this have yet to take root...

Report · Dec 06, 2017

Adobe occasionally adds/adjusts APIs for applications between application versions

How does that work? Whenever they release something it get's a new version number right??

What's wrong with the current approach you have, organizing them in a folder with the version number (e.g. 2015.3)? it looks fine to me.

2) I just checked out the "reflection" property and wrote a little script to dump all it's information in the whole $.global object.

Unfortunately you can only get some type information from it, no descriptions / helps seems to be filled in.

var handled = []
function unreflect(obj) {
if (!obj) return
var result = {
    methods: {},
    properties: {},
    children: {}
}
if (obj.reflect) {
    for (var i in obj.reflect.methods) {
      try {
        const method = obj.reflect.methods
        result.methods[method.name] = {
          dataType: method.dataType,
          help: method.help,
          description: method.description
        }
      } catch (err) {}
    }
    for (var i in obj.reflect.properties) {
      try {
        const property = obj.reflect.properties
        result.properties[property.name] = {
          dataType: property.dataType,
          help: property.help,
          description: property.description
        }
      } catch (err) {}
    }
}
for (var i in obj) {
    if (typeof obj === 'object' && handled.indexOf(obj) === -1) {
      handled.push(obj)
      result.children = unreflect(obj)
    }
}
return result
}
$.writeln(JSON.stringify(unreflect($.global)))

I guess we could modify one of the OMV scripts in here (on macOS): /Applications/Adobe ExtendScript Toolkit CC/ExtendScript Toolkit.app/Contents/SharedSupport/Required/

And have it dump useful stuff to a file?

Anyways, I agree that ideally we would get the omv XML files for the different apps & versions from Adobe.

Otherwise we will just have to do it by hand I guess

Report · Dec 07, 2017

vespakoen wrote
Adobe occasionally adds/adjusts APIs for applications between application versions
How does that work? Whenever they release something it get's a new version number right??
What's wrong with the current approach you have, organizing them in a folder with the version number (e.g. 2015.3)? it looks fine to me.

Adobe can add/adjust APIs whenever they release a new update to the software. Currently, Premiere Pro is at v12.0.0. When/if they release v12.0.1, it is possible that they might add an API or two. This would require a separate declaration file. As such, it may make better sense to store the folders as follows:

PremierePro
- v12.0.0
  - index.d.ts
- v12.0.1
  - index.d.ts
- v12.1.0
  - index.d.ts
- index.d.ts // latest version

The official Node Type Declarations have a similar setup. In the above example, the version numbers could also be the CC version, although it may be better to align by application version, which is what CEP seems to use in the Manifest files...

Also, to be fair, I'm not the maintainer/owner of the repository that contains declaration files sorted by CC version. That would be pqiorpa.

vespakoen wrote
2) I just checked out the "reflection" property and wrote a little script to dump all it's information in the whole $.global object.
Unfortunately you can only get some type information from it, no descriptions / helps seems to be filled in.

Right. The XML files that back the Object Model Viewer for ExtendScript and ScriptUI documentation would be better to target.

vespakoen wrote
I guess we could modify one of the OMV scripts in here (on macOS): /Applications/Adobe ExtendScript Toolkit CC/ExtendScript Toolkit.app/Contents/SharedSupport/Required/
And have it dump useful stuff to a file?

Did you perhaps mean /Library/Application Support/Adobe/Scripting Dictionaries CC/CommonFiles/ ? Those are the XML files that provide type information to OMV, as I understand it... I believe parsing these is exactly what pqiorpa did to generate the core API declaration files, as I understand it.

Unless you mean that some of the files you pointed to are what powers the OMV's ability to "discover" APIs? Even then, I'm entirely convinced that this gets us everything. Type information, at least, appears to come through, which is good. However, these would not have documentation, which would be unfortunate.

vespakoen wrote
Anyways, I agree that ideally we would get the omv XML files for the different apps & versions from Adobe.
Otherwise we will just have to do it by hand I guess

I would go a little further, honestly! To my mind, ideally, Adobe would provide first-party support of this effort and drive it. Imagine a world where engineers add new ExtendScript APIs and provide us end users with documentation! In this world, Adobe would release an update to SomeApplication CC 20XX and simultaneously (or near enough) update the CEP GitHub with updated declaration files. While there are admittedly many forms that documentation can take, my personal preference would be TypeScript declaration files. Not only are they almost zero-cruft (no XML/HTML-style tags which keeps them readable), but they can be added to many, many modern IDEs to power both JavaScript and TypeScript autocomplete features and inline documentation. Readable and functional...

In lieu of first party Adobe support, it's looking like a rather manual process to make things as helpful as possible. Certainly the declaration files should start from something automatic, though...