API Reference for Liferay's Global JavaScript Object

Tobias Szczepanski, 8 Jaren geleden aangepast. New Member Berichten: 23 Aanmelddatum: 31-10-17 Recente berichten
Hi everyone,

first off, I am entirely new to Liferay and so far I do struggle with Liferay's way of documenting things, which seems to me very high-level and lacking proper API references.

The issue I have in particular is to create and/or reuse a modal window (or popup window). By default Liferay comes with AlloyUI. The latest AUI provides a Widget and a specialised Modal. The global JS object Liferay provides the following:
Liferay.Util.Window
Liferay.Util.getWindow(event, config)
Liferay.Util.openWindow(config, callback)
Liferay.Util.openInDialog(event, config)
Liferay.WidgetZIndex()

Where is the documentation for this API?
What's the signature of the config object?
How does this API relate to the AlloyUI Widget and Modal?
What is the best practise for creating / displaying modals in Liferay 7.0?

Any help is much appreciated. Thanks!
thumbnail
David H Nebinger, 8 Jaren geleden aangepast. Liferay Legend Berichten: 14933 Aanmelddatum: 2-9-06 Recente berichten
Tobias Szczepanski:
I do struggle with Liferay's way of documenting things, which seems to me very high-level and lacking proper API references.


This is a common complaint shared by many, including me. So you're not at all alone here...

Where is the documentation for this API?
What's the signature of the config object?
How does this API relate to the AlloyUI Widget and Modal?
What is the best practise for creating / displaying modals in Liferay 7.0?


There is no easy answer for any of these. Often times as a developer if I want to do something in AUI I go to the Liferay source after I've found an example of how they do something that I want to mimic. The source will show me how Liferay did it and that tends to be the best starting point I've found to do something similar. Going to the latest AUI docs is not always the best path because AUI releases independently from Liferay, so the latest AUI docs might not represent what has actually been released in Liferay.

As far as best practice, well that too is hard to say. Liferay actually allows you to use jQuery, AUI, or many other JS frameworks. You won't see Liferay anywhere saying "Use Bootstrap's JS for X, Y and Z" because that may turn away folks that have a big YUI staff (does anyone besides Yahoo have a big YUI staff?).

So Liferay won't say it is best to use AUI or jQuery or ... because they want you to feel comfortable using what you may already know.

That said, I usually go to the Liferay source. If some implementation is good enough for the Liferay UI, it is usually good enough for me plus I won't have to figure out how to pull in and use another framework at the same time coexisting in the Liferay environment.
Tobias Szczepanski, 8 Jaren geleden aangepast. New Member Berichten: 23 Aanmelddatum: 31-10-17 Recente berichten
Thank you very much for your reply. Well it's very sad, that Liferay doesn't care about developers, but that's just how it seems to be. At least now I have clarity.
David H Nebinger:

As far as best practice, well that too is hard to say. Liferay actually allows you to use jQuery, AUI, or many other JS frameworks. You won't see Liferay anywhere saying "Use Bootstrap's JS for X, Y and Z" because that may turn away folks that have a big YUI staff (does anyone besides Yahoo have a big YUI staff?).

I got rolled onto a project where they use just all the default libraries Liferay comes with. So basically they use an Atlas-Theme and customise it. As far as I understand that includes Bootstrap, Lexicon, Clay, YUI, AUI and custom Liferay implementations. In this default case it is absolutely intransparent to me when to use what APIs/Framework. If I use AUI.Modal it seems to conflict with Liferay.Util.openWindow(). But as it seems unfortunately I'll have to build a time machine to find the time for digging deep into this Software.

Best regards
thumbnail
David H Nebinger, 8 Jaren geleden aangepast. Liferay Legend Berichten: 14933 Aanmelddatum: 2-9-06 Recente berichten
Tobias Szczepanski:
Well it's very sad, that Liferay doesn't care about developers, but that's just how it seems to be.


It's not all that bad. They realize documentation is an issue and they are working on resolving that.

My guidance still stands - if you are wondering how to do something using the standard Liferay libraries, find another example from the Liferay source and lift it use it as a guide.
thumbnail
Michael Williams, 8 Jaren geleden aangepast. New Member Berichten: 19 Aanmelddatum: 14-3-14 Recente berichten
Hi Tobias and welcome!

First let me say that your comments have not gone unheard. I'm sorry that you weren't able to find what you were looking for. As David pointed out, we're aware of the API documentation gaps. We're working on it and we'll be focusing on new code and old but high-profile code in the future. We have some of the APIs documented here: https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-0/liferay-javascript-apis but again, this is an ongoing effort that will improve over time.

Thanks,
Mike
Tobias Szczepanski, 8 Jaren geleden aangepast. New Member Berichten: 23 Aanmelddatum: 31-10-17 Recente berichten
Thank you all for your answers!
Michael Williams:
First let me say that your comments have not gone unheard. I'm sorry that you weren't able to find what you were looking for. As David pointed out, we're aware of the API documentation gaps. We're working on it and we'll be focusing on new code and old but high-profile code in the future.

That's good, since a product with an expensive license like Liferay DXP should come with proper documentation. It would definitely be much appreciated and I am certain it would also yield in a higher market share for Liferay DXP ;)
Andrew Jardine:
Wow. Yeah, this is probably the most inaccurate statement I have read about Liferay in quite some time. I think what you meant to say was --

First off, let me clarify to you that I am not talking about CE but DXP. Secondly, how is it inaccurate, if I encountered the topic of lacking documentation several times from several sources within the two weeks I've learned about Liferay? How is it inaccurate if Liferay staff admits that their documentation is lacking? It is a provocative statement of me to say "it seems like Liferay doesn't care about developers". But I do believe that if you do not document your code, you basically do not care about any other developer that has to work with it later on. Even if your code is clean as hell, documentation of system-specific APIs is a must. Furthermore it's provocative nature is meant to emphasise that this is not what an licensed product should be lacking.

Don't get me wrong here, I am not bashing or complaining about the Software, so far the Portal seems to me like a really powerful and sophisticated piece of software and Liferay did a great job on that! Just the fact that the documentation is lacking to this extend is a no-go to me. In the end Liferay as a company will benefit from proper documentation the most, since it will increase cost efficiency as well as developer's satisfaction working with Liferay, means we would see more Liferay DXP projects overall.
thumbnail
Andrew Jardine, 8 Jaren geleden aangepast. Liferay Legend Berichten: 2416 Aanmelddatum: 22-12-10 Recente berichten
We'll have to agree to disagree on this one I guess. Of course Liferay is going to say the documentation could be better -- what counter argument do they have?! emoticon

Documentation for just about every piece of software I have every worked with (sold by a vendor) is lacking. I think you missed my point -- it's not about abandoning developers at all. Would you rather have several thousand pages of documentation telling you how to structure a project by hand? or a tool like Blade, or Liferay IDE that does it for you? To me that is an example of how they are making decisions that HELP developers with their every day work.

I would also argue that your point about having a DXP license is irrelevant. The license for DXP is your typical Open-Source-Enterprise. You are paying for patches/security fixes/support. You also may not be aware but unlike the big competitors, IBM, Oracle, etc, Liferay licensing doesn't cost millions to get up and running with complex formulas about how many clock cycles and which OS you are using blah blah blah. In fact, in terms of enterprise licensing I'd say it is cheap, dirt cheap, for what you get.

I'm not arguing the lack of documentation. I'm arguing your statement that somehow that means Liferay doesn't care about the people that use it.
Your version of proper documentation, I have rarely found useful anyway. There are plenty of products out there with stupid shit like --

long productId
A numeric identifier that uniquely identifies a product


I don't need someone to write that down for me. That kind of obvious documentation isn't worth the electricity used to render it on my screen. Most of the time, if I want something "documented" its a problem that is difficult for me to solve -- probably unique to my client, or too complex to write in a one page tutorial. I spend 90% of my day reading and writing code. When I need an answer, I open the source code and look (by the way, this is something that Liferay does that not many vendors do. Oracle has never shared with me their source code for ANY product I've licensed from them).

I am guessing that you are new to the product so you have not yet picked up the naming conventions, the design patterns etc that the portal uses. I was once new to the product as well, and believe me, I remember how frustrating it was as well. I am sympathetic to your situtation which is why I try to help on the forums as much as I can, often trying to provide an explanation not just an answer. In fact a lot of us long time Liferay developers have had to near start over again when 7 was introduced with the new architecture. You think you have it rough now? you should have tried this 2 years ago! Not only was their little documentation, what was out there was inaccurate or out of date! emoticon

There is certainly a time investment required to obtain a critical mass of knowledge in the product to be good with it. I think the most common back end stuff is documented pretty well on the developers portal -- the front end stuff? yeah lacking. But most front end people want to use their own stuff anyway and don't care how Liferay does it. Very few people have come to me and said "Can you teach me how to us AUI?" .. it's more like "How can I use Angular instead of AUI".

Final note. The community for Liferay is really supportive so what it lacks in terms of documentation you will find can be made up for with the community. My advice would be to use the slack channel and this forum (as you have been) to compensate for the gaps -- but dig into the source. I am always surprised by the number of developers I work with who don't even bother to download it. The source has all your answers. That's why they say "To find the truth, you need to go to the source."
thumbnail
Jack Bakker, 8 Jaren geleden aangepast. Liferay Master Berichten: 978 Aanmelddatum: 3-1-10 Recente berichten
Every once in a while there is a forum thread like that one long ago "Liferay sucks" which was like a dirty snowball rolling down a hill.

"Liferay doesn't care about developers". Well, I don't think the software itself has become sentient, so this must be an accusation that Liferay staff and community members don't care about developers. As a developer, my experience with those Liferay staff and community that I have come into contact with has indicated to me that Liferay inside and out are very caring and very willing to help where they can.

As far as the need to improve documentation: Yep, there are those looking to do that as they chase the ever moving ship to help get others on board which in turn should help it along.
Tobias Szczepanski, 8 Jaren geleden aangepast. New Member Berichten: 23 Aanmelddatum: 31-10-17 Recente berichten
Andrew Jardine:
Your version of proper documentation, I have rarely found useful anyway. There are plenty of products out there with stupid shit like --
long productId
A numeric identifier that uniquely identifies a product


Common man, really? Obviously bad documentation is as worthless as the absence of documentation. Let's stop this argument here.
I understand you are emotional about this and proud of your journey with Liferay and kudos (!!!), it surely is not an easy thing to wrap one's head around Liferay atm. But do you really believe that with proper documentation one would not be able to understand the system exactly the same just faster? But yeah I agree to disagree emoticon
Andrew Jardine:
That's why they say "To find the truth, you need to go to the source."

Have fun finding the "truth" in here /modules/apps/foundation/frontend-js/frontend-js-aui-web/src/main/resources/META-INF/resources/liferay

Anyways, this topic is clarified for me and hopefully will be so for others with the same questions, too. I am not here to bash on Liferay. My original four questions were all answered and anything else is just off-topic.

Again thanks for everyone's input! emoticon
thumbnail
Jack Bakker, 8 Jaren geleden aangepast. Liferay Master Berichten: 978 Aanmelddatum: 3-1-10 Recente berichten
The truth shall set you free.
thumbnail
Andrew Jardine, 8 Jaren geleden aangepast. Liferay Legend Berichten: 2416 Aanmelddatum: 22-12-10 Recente berichten
Good morning Tobias,

I don't think anyone i contesting that the documentation is lacking, or in some cases could be better. The statement that was being refuted was your statement that the lack of documentation was somehow Liferay turning their nose up at developers. That is simple not true.

The truth in there, and it's no better or worse than any other foundation module, or web experience module, or portal-impl class. I understand your point about digging through the source is always more work. In fact, truth be told, a lot of the time when I am helping someone here, I find myself digging through the source trying to find something to help them. I was trying to point out the silver lining to your dark cloud -- you will inevitably learn something else along the way as well because it forces you to look closer at the portal itself.

Anyway, this horse is most certainly dead and bordering now on becomes a puddle. If you have any more questions, don't hesitate to ask. We're all happy to help.
thumbnail
Richard Sezov, 8 Jaren geleden aangepast. Regular Member Berichten: 220 Aanmelddatum: 7-2-07 Recente berichten
Hi Tobias,

I didn't respond to this thread before, because I was processing the results of the Liferay documentation survey we'd run earlier in the year. I hope you had a chance to participate in the survey; if you didn't, we plan to run another one next year. In any case, my hope is that the survey addresses your concern about how Liferay views developers: we are actively seeking ways to improve the documentation and soliciting any feedback we can to make sure we're doing the right things.

We hear your feedback about the API docs loud and clear; in fact, we knew there was a problem, and we are doing specific things to address it. Have a look at the survey results, and if you have any further feedback, questions, or comments, please feel free to share them. That's the only way we'll learn where our blind spots are, and the only way we'll be able to address them.

Thanks!
thumbnail
Andrew Jardine, 8 Jaren geleden aangepast. Liferay Legend Berichten: 2416 Aanmelddatum: 22-12-10 Recente berichten
Well it's very sad, that Liferay doesn't care about developers, but that's just how it seems to be. At least now I have clarity.


Wow. Yeah, this is probably the most inaccurate statement I have read about Liferay in quite some time. I think what you meant to say was --

Well, it's very sad. I'm really frustrated because I would love to be able to leverage more of the great free product without having to spend hours reading the source


-- yes, it can be frustrating, but I am guessing you are pretty new to Liferay and have not yet grasped the monumental size of this product. Once you have, and realize that it doesn't boast a couple dozen features but rather several hundred features you might have a better appreciation for both the scope of what you are asking for and the effort that would be required. I think we all get frustrated when we want the answer "NOW" but can't find it, but rather than look at it as "a company that doesn't care", consider it an opportunity to learn something new about the product. I would asy that 90% of what I know about Liferay comes from digging through the source code.

Don't forget that Liferay is still open source for the vast majority of it's users. If you want to help make the product better, and you have identified a gap, maybe you should consider contributing to the documentation as you learn new bits and pieces. Liferay, the organization, may carry the torch, but the community can always help to make it better.