TypeScript definitions #88
Comments
|
Hi romanov, this is interesting but currently not planned. However it might be easy to achieve based on the control metadata. I'll leave this ticket open as inspiration for a possible enhancement. Regards |
|
I would definitely be interested in a TypeScript definition. We've been generating one using a JSDoc plugin, but it's error prone and requires a lot of manual intervention. Using the control files or something similar would much more reliable. |
|
I am interested as well. |
|
Hi Sirs, Thank you & SAP for all the good code. -- Roberto |
|
@RobertoMalatesta |
|
Hi @afrische, your github project looks promising and useful, I will follow it. On typing: by using Generics,Interfaces and Classes UI5 could get a cleaner construction/implementation system, using Abstract Data Types and Contract-based Programming, leveraging TS concepts, syntax and tools. As an example: in the code you quoted, having to pass an Interface instead of a JSON Object would lead to a more documented and safer code. Grüße R |
|
+1 for TypeScript. |
|
+1 |
|
+1 - would love to see .tsd files for OpenUI5! |
|
not only .tsd, but TSX/JSX could be used for declarative UI there is no need for custom XML UI schemas in 2016. |
|
+1 for typescript definitions. I guess it should be possible to generate those from the JSDoc. This way private API would be excluded from the types automatically. |
|
the typsescript defintion file would automatically enable intellisense for UI5 coding in Visual Studio Code since this is there mechanism to retrieve type information: https://code.visualstudio.com/docs/languages/javascript#_intellisense |
|
There is a (highly experimental) GitHub project which generates TypeScript definition files from JSDoc. I haven't tried it yet, but seems promising nonetheless: https://github.com/englercj/tsd-jsdoc |
|
For me the angular project https://github.com/angular/dgeni-packages seems to be the most promising. Mark Schmale also hacked together a script to extract type definitions from the api.json: hth |
|
Hello, It declares classes, enums (string literals) and typedefs. I put in some text fields to replace types and there is a version selector for deprecated methods. I am a beginner in both, typescript and ui5 and I get a lot of errors now. I fixed the most obvious stuff, but now I get compiler errors regarding inheritance inconsistencies and therefore, I have to have more experience with this stuff. Perhaps someone (hopefully more experienced than me) has the time to have a look at the files and can help me improve the procedure. Help much appreciated. I am missing all the constructor parameter declarations so far and I am also not sure, if the documentation is always correct, as I got some interesting type specifications out of the json file? Cheers |
|
Little update: The TS parser works now and I created definition files for the whole project. Would it be possible to adjust your documentation to fit better to type script? There are some incosistencies in the type descriptions. Annotation:
Cheers |
|
Some of the entries are obviously misspelled types and need to be fixed, others seem to be valid. I took a quick look and came to the following classification: Typos, JSDoc Syntax, Inconsistencies (fix)
Unqualified References or Wrong Package (fix)
Visibility / Missing Documentation (should be fixed, but not necessarily as suggested)
Native APIs (see e.g. https://developer.mozilla.org/en-US/docs/Web/API), Thirdparty
UI5 basic types / JSDoc convention (won't fix, map generically)
Correct? (not clear why they had to be mapped)
Open
[UPDATE] List above updated with fixes, added some more comments. |
|
Hello, |
|
Thanks to your great documentation I got a stable version now. The working typedefs are in my repo. Maybe you have a use for the parser to check your documentation. If you skip all replacements I added it will fail horribly :) Here are some further questions:
If someone uses these definitions I would be glad for some feedback. I hope I can adjust it so much to get reliable typedefs automatically from your api reference. Check for regular updates. |
|
I've made a lot of fixes now (see linked change), but some issues still are open, mainly:
|
|
Thanks @apazureck 👍 Did you consider uploading these definitions to Definitely Typed If you do so it would be possible to consume these artifacts easily via npm.
|
|
Actually, that was my plan, too :) We are currently using the declarations in our project and I am thinking of some ways to improve the declaration file converter. Sadly I do not have the time to do that right now, as it would need some more adjustments to the ts files to make them reflect the content of UI5 properly:
would be written in ts like that: |
|
1_manual_coorections : if you encounter these small errors it is almost as much effort to make a pull request here on github as manually correct them in the definition file. Github has a very nice workflow for small edits 2_jquery see https://github.com/afrische/ui5.d.ts/blob/master/jquery.sap.d.ts 4_modules_vs_define these are two very different implementations of the same concept. Don't conflate them, please. Typescript almost uses the ES6 module system. ui5 has its own module system. I don't think this is a good place to spend effort right now. Personally i did not upload my definitions to definitelyTyped because they don't meet the quality expectations a reasonable user should have of that repository. What's wrong with a git submodule? |
|
Reg. 1: can you elaborate a bit more on that (examples)? Do you want to determine overloaded signatures out of the optional markers for params? That might indeed be hard. To be honest, we didn't know JSDoc's concept of API "variants" when we started the documentation, might have been a better choice. Reg. 4: to get rid of
... |
|
Hi @apazureck and all, I like the approach : but it definitely has some issues: sap.ui.define'd classes are not discovered by intellisense without writing some other verbose information that adds up to the verbosity and maintenance cost of a project. The problem is that we have two inheritance systems: one by Typescript and the UI5 one. I skimmed through UI5 inheritance code some time ago to see if I could get out with some defs automatically then I formed the opinion that the best would be to convert to TypeScript the whole UI5, making use of interfaces for writing and documenting using pure JS/TS class hierarchy for components. It can be done, albeit it's not trivial given the size of the source. I see only advantages in
Until then I will go with a simple Just my 2 eurocents. --R |
|
OK, maybe @RobertoMalatesta is not using it with great success :) Another question: |
400k UI5-specific TS lines and counting. |
|
@apazureck @RobertoMalatesta I will give it a try ;) I'm new to Typescript but know the principle. Comming from C# Edge many features are known. And it looks really nice and the benefits are huge. I can understand that SAP is 3-5 years behind the up-to-date development tools, because business isn't that fast but I can't understand why they prefer Javascript for Business Development. It's originally designed to make some fancy animations or effects in the Web Browser... |
|
I am also coming from C# and I can tell you gonna like typescript. The nice touch is if you have WPF experience many things in openUI5 will be familiar (xml, databinding, etc.). And If you do not develop many custom controls, then you will not have any issues using hacky workarounds. I had no need to create custom controls so far, as we always found a solution built in openUI5. But we are working the way to make a compromise between the crazy things our design team wants and what openUI5 provides (who wants a GUI anyway?!). I have to admit I like Typescript even more right now, as you can do some cool stuff due to js allowing very much. so you have advantages from both, a strongly typed system like in C# and a very flexible typesystem in js. And oData is great btw. (at least if you have ASP.NET + EntityFramework Backend), don't let anyone tell you otherwise ;). I have written a Proxy and Interface generator and its just great when our backend gets updated I just can check if my classes will still work that way. And the auto paging of some controls, like the Table is pretty neat. |
|
I am using typescript+sapui5 with ES2015 imports. I create a decorator (to handle inheritance in the ui5 way, calling a static extend method on base class) and I create a define function that translates the TypeScript AMD generated define() call into a sap.ui.define call. Here is an example, intellisense is working fine with both sap.* namespace and my own classes: I create a NPM package to make it reusable: https://www.npmjs.com/package/ui5ts |
|
Hi @lmcarreiro, That is really great! I have a half-finished generator for modular typescript definitions (no namespaces) with some extra spice, like templated events and models. I wanted to use the typescript compiler api to modify the ast, but it is quite instable, so I skipped this idea. What a great approach of yours. I hope I have some time the next weeks to give it a shot, but I will tell my colleague, maybe he can try it. cheers! |
|
Why are you reinventing a wheel? What's wrong with ExtJs or Isomorphic
SmartClient which is in development since 1998! And you are using jQuery in
2017 UI? :)) Such a waste of time, better contribute to existing tools than
reinvent.
…On Oct 9, 2017 11:59 AM, "Andreas Pazureck" ***@***.***> wrote:
Hi @lmcarreiro <https://github.com/lmcarreiro>,
That is really great! I have a half-finished generator for modular
typescript definitions (no namespaces) with some extra spice, like
templated events and models. I wanted to use the typescript compiler api to
modify the ast, but it is quite instable, so I skipped this idea. What a
great approach of yours. I hope I have some time the next weeks to give it
a shot, but I will tell my colleague, maybe he can try it.
cheers!
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#88 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AEAcnHZjxJ1E-77AH9dOmcEmWa9liqWHks5sqeBegaJpZM4CLP7w>
.
|
|
@apazureck The bottleneck are the UI5 definitions, when you start writing core using TypeScript you end up finding a lot of differences between UI5 API documentation and the TS definition files. |
|
Actually I've written a couple of decorators for using ui5 in typescript too. Feel free to include them in your library @lmcarreiro . They also have some support for ui5 aggregations and properties by turning them into native javascript getters and setters and under the hood call the ui5 model. export function UI5Class(namespace: string) {
return function (originalConstructor) {
const ui5ClassDescriptor: any = {
metadata: originalConstructor.metadata,
constructor: originalConstructor
};
// copy over static renderer property for controls
if (originalConstructor.renderer) ui5ClassDescriptor.renderer = originalConstructor.renderer;
/**
* Extract all prototype property descriptors and later assign them back to the ui5 generated to prototype (and don't pass them to the .extend class descriptor).
* The reason is basically that UI5 doesn't handle ES5 getters and setters and some other edge cases of special properties properly, when defining them on the .extend class descriptor.
* Side comment: Probably UI5 should rather copy over / analyze the *property descriptors* instead of the actual *properties* to avoid those problems.
*/
const staticPropDescriptors = Object.getOwnPropertyDescriptors(originalConstructor);
const prototypePropDescriptors = Object.getOwnPropertyDescriptors(originalConstructor.prototype);
const BaseClass = Object.getPrototypeOf(originalConstructor);
const ui5Constructor = BaseClass.extend(namespace + '.' + originalConstructor.name, ui5ClassDescriptor);
Object.defineProperties(ui5Constructor.prototype, prototypePropDescriptors);
Object.entries(staticPropDescriptors).forEach(([key, descriptor]) => {
if (typeof ui5Constructor[key] === 'undefined') Object.defineProperty(ui5Constructor, key, descriptor);
});
return ui5Constructor;
}
}
export interface IPropertyOptions {
type: 'string'|'boolean'|'int'|'float'|'object'|'any'|'string[]'|'boolean[]'|'int[]'|'float[]'|'object[]'|'any[]'|string;
group?: 'Accessibility'| 'Appearance'| 'Behavior'| 'Data'| 'Designtime'| 'Dimension'| 'Identification'| 'Misc'
defaultValue?: any;
bindable?: true|'bindable';
}
const defaultPropertyOptions : IPropertyOptions = {
type: 'any'
};
export function UI5Property(options?: IPropertyOptions) {
options = Object.assign({}, defaultPropertyOptions, options);
return function (prototype, propertyName) {
const constructor = prototype.constructor;
constructor.metadata = constructor.metadata || {};
constructor.metadata.properties = constructor.metadata.properties || {};
constructor.metadata.properties[propertyName] = options;
Object.defineProperty(prototype, propertyName, {
get(){
return this.getProperty(propertyName);
},
set(value){
this.setProperty(propertyName, value)
}
});
}
}
const aggregationDefaultOptions = {
multiple: false,
visibility: 'public'
};
export interface IAggregationOptions {
type?: string;
multiple?: boolean;
singularName?: string;
visibility?: 'public'|'hidden';
bindable?: true|'bindable';
}
export function UI5Aggregation(options?: IAggregationOptions) {
options = Object.assign({}, aggregationDefaultOptions, options);
return function(prototype, aggregationName) {
const constructor = prototype.constructor;
constructor.metadata = constructor.metadata || {};
constructor.metadata.aggregations = constructor.metadata.aggregations || {};
constructor.metadata.aggregations[aggregationName] = options;
Object.defineProperty(prototype, aggregationName, {
get(){
return this.getAggregation(aggregationName);
},
set(value){
this.setAggregation(aggregationName, value)
}
});
}
}here's a small usage example: // ... imports of Controls etc. above
@UI5Class('my.ui5.controls')
export default class MyControlWithBusyIndicator extends Control {
@UI5Aggregation({visibility: 'hidden'});
busyIndicator = new FlexBox({
fitContainer: true,
height: '16em',
alignItems: 'Center',
justifyContent: 'Center',
alignContent: 'Center',
items: new BusyIndicator({text: '{i18n>busy_text'})
});
@UI5Property()
isBusy = true;
@UI5Aggregation()
content: Control;
static renderer = (rm, oControl: MyControlWithBusyIndicator) => {
rm.write('<div');
rm.writeControlData(oControl);
rm.write('>');
if (oControl.isBusy) {
rm.write('<div> Loading... </div>');
} else {
rm.renderControl(oControl.content);
}
rm.write('</div>');
}
}
const myControl: MyControlWithBusyIndicator = /* getting a reference from the control from somewhere */;
myControl.isBusy = false; // sets the ui5 property, triggers rerendering etc. - no need to call myControl.setProperty('isBusy', true) or anything like that. (even though this is exactly what will be called under the hood) |
|
@lmcarreiro, I just used controllers so far and did not do any custom components, so it worked pretty well most of the time. @lmcarreiro @geekflyer maybe we could think of a repo to work on that topics together. I could provide the definition parser, a project template with bsync and my extension for vscode with naviation and autocomplete. I would like to merge this together to get better, simpler and more stable code. I'll see what I can do on the parser the next weeks. |
|
@apazureck I'm not actively working on ui5 anymore (my stack is nowadays ts + react + mobx) but feel free to use whatever code I've posted above and put it into your repo. Btw I'm also looking for a maintainer for https://github.com/geekflyer/openui5-mobx-model which works nicely together with typescript ^^. |
|
@geekflyer, I started working with ui5 three weeks ago, but as soon as I understand your decorators better, I will certainly put them into my npm package and deprecate my own. It was a good idea of yours to put just the namespace in the UI5Class decorator parameter and get the name of the class from the originalConstructor, this way you don't have to write this name two times, like in my UI5 decorator. @apazureck, It's a good idea, I don't know if I will have the time needed to contribute, but we can try. In my example https://github.com/lmcarreiro/ui5-typescript-example I got some errors because the differences between @types/openui5 definitions and the API. I'll try with your's and help fix things if I found something different than the API docs. |
|
+1 |
|
Is there any chance that somebody (@apazureck?) updates openui5 definitions at definitelytyped? |
|
@emumanu I recently published some openui5 types to npm. The module name is |
|
The problem with the typings is that the UI5 Framework does not really play along with ES and, thus, typescript. The inheritance system would need a custom typescript compiler flavor. I started have a look at the typescript compiler api, but it did not lead anywhere. @lmcarreiro did a great job on writing a decorator and the define function to use the ts compiler with amd. I think personally it is the best approach to UI5 with typescript so far. I wrote typings generator, which plays along with that decorators. Sadly, as I see, @r-murphy did write a parser, too. I don't know how far you are for now, but you can have a look at my declaration parser it at the development branch. I contacted @lmcarreiro to get the typings up and running with his plug-in, but it did not work out so far. And I did not have the time to have a closer look at it. It would be nice if we could work to gether on that, so there are not ten parsers and typings out there. My Parser:
I did You can see the typings in action at https://github.com/apazureck/ui5-typescript-example. Maybe you can have a look at them and get them to work. @lmcarreiro did adjust his functions, but I did not get them to work so far, but did also not have that much time the last weeks :( In the long run it would be nice if we could put our effort together and maybe we could turn @lmcarreiro 's or @r-murphy 's npm packages in some kind of ui5-cli to create the declarations and do other stuff (like controllers, classes, etc.). In my opinion it would be best to have one central place where typescript for UI5 happens. EDIT: Just to be clear, I don't care which parser is used to get what typings, but I think there should be only one parser, which puts out the typings instead of maintaining different typings. Sadly I did not tell earlier that I was doing something so we did the same thing two times :( It would be great if we could work on one parser together and one npm package to provide typescript. |
|
Thank you for the quick replies. The reason I was asking is because I wanted to use a c# to javascript converter to work on OpenUI5. The c# assemblies for the converter are based on the typescript definitions at definitelytyped. I hope you (@apazureck, @r-murphy and @lmcarreiro) could unify your efforts to get the best typescript possible for UI5, and if you can, please update the definitions at definitelytyped. That way, more people that don't know about this thread can also learn about your typescript effort on OpenUI5. For example, the guy who updated definitelytyped has another parser: Maybe there's some useful ideas for you there. BR |
|
@apazureck Yes I agree that we should collaborate and try to consolidate. I'll reach out to you outside this thread. I like some of the approaches used in your generator. However as of now it doesn't work for my apps. My generator is actually a fork of @lmcarreiro's so I didn't write it from scratch. I have a few enhancements planned, but as of now it generates types used in 5 production apps at my work, with more being converted and tested now. Prior to the generator my team was manually editing and using the types from definitelytyped, but we wanted to get a working generator as a more maintainable approach. And for transforming the ES modules and classes into UI5's module and class system, I have a babel plugin for that, rather than using decorators. babel-plugin-transform-modules-ui5. This plugin also works with non-typescript ES classes and modules and actually pre-dates converting our apps to typescript. And an example of both in action. @emumanu I've avoided definitelytyped so far since my generator is in the early stages. But I think you're right that we should aim to get something on there for easy discoverability. |
|
@r-murphy: Sounds great, I am looking forward hearing from you. I did not find the time lately to work on the parser. I don't think that will change until end of April. So if you have the time to go on feel free to take what you need. But in my opinion we should discuss how the typings should look like, first. I hoped once the parser would be provided for example by @lmcarreiro's npm package the discussion about how the typings should look like would start. But I think it is better to fiure that out first, as there may be some breaking changes. I am talking about how to resolve imports and how you can do exports in your module so the ts compiler will put out good js in the first place. I did not have a closer look at babel so far. But as I understand it transforms javascript to other javascript, so the mappings would not be correct anymore, do they? Does your plugin solve that problem? So it would only be for distribution purpose, I guess. Is that correct? |
|
Linked to: Bridge-Forums |
|
Hello everyone. Please Checkout this mono-repo: Specifically the @openui5/ts-types package.
Feedback & Contributions always welcome 😄 |
|
For the TypeScript fans in this thread, I would like to mention the |
|
Hello @akudev. |
|
@bd82 The recording is now available here: https://www.youtube.com/watch?v=0notj9PPTho Let's re-open this issue to make it formally clear that there is progress and active work. |
|
@akudev |
|
As TypeScript type definitions are being regularly released since 1.90, I close this as fixed. In addition to the definitions, there are example applications in TypeScript, incl. custom controls, there is a control library in TypeScript, a watch tool helping with control development, and hints how the type definitions even can help when developing in JavaScript in previously existing applications. Links to all these resources can be found at https://sap.github.io/ui5-typescript (which is going to be updated as new content is created). That repository is also the location for tracking issues and enhancing the definitions further. |
and others
Is there any plan to release definitions for TypeScript?
The text was updated successfully, but these errors were encountered: