Collaborating on Documentation

[vince.clark]

This is a follow up to the Jan 21, 2022 community call. Our main topic was documentation to help speed the learning curve of developers that are new to Moqui.
Please see the content below as an initial attempt to build out the various topics that need to be covered. Obviously plenty of subtopics that could go under each bullet.

As I mentioned in the call, we can leverage existing documentation and continue building upon it. I have linked to some of it in the list. We can move this to a proper home later, which leads us to…

Action Items:

• We need a home for documentation that allows multiple people to contribute, track versions, review process, and publishing. We discussed a few options from a) using the current state (I think the wiki within moqui.org?) to b) a new “moqui-docs” github repo, and c) even something like a wikipedia model, meaning anyone can write anything and it is community maintained / monitored / corrected.
• Start writing! Anyone in the community that has been working with Moqui by definition knows more than anyone new to the project. It is OK if it is informal and unpolished. If you have learned something useful then share it. I am happy to curate content as we get this going, or just…
• Post on the forum. Questions and comments on the forum build up our knowledge base and are as good, and sometimes even better than, structured documentation.

Topic Areas

• Introduction to Moqui
• Installation
• Development Environment
• Guided Tutorials
  • Quick Start
  • Additional tutorials with increasing complexity (To Be Defined)
• Users, Roles, and Permissions
• Universal Data Model (UDM)
  • Party
  • Include full list from here
  • Enumerations, Types, Statuses, and Purposes
• Universal Service Library (USL)
• Universal Business Process Library (UBPL)
• User Interfaces and APIs
  • Themes - customizing the look and feel
  • Screens and Subscreens
  • Menus
  • [XML Screens and Forms](XML Screens and Forms.md) - default way to build interfaces
  • Other Tools - React, etc.
  • RESTful Web Services
• Elastic Search

[Mohammad_Al_Hajj]

Thank you for this post. I have been asking for it for 8 months.

Would you please consider adding concrete examples in the docs? I found it drastically quickened my learning time. My main problem in the past was finding the examples.

Would you also consider providing a standardized shape for the docs? For example, adding an example under each concept/“UI component”.

Finally Would you be willing to start your documentation by making sure that all XSD files are fully documented and expanded upon? I have, on not-so-few occasions, found tags and attributes that i am interested in, to be missing any documentation.

If it is easy to join, i am willing to help you with documenting the java code in the framework/runtime.

[vince.clark]

Thank you for your interest @Mohammad_Al_Hajj, yes your help with documentation is welcome.
We have not yet worked out details on a repository so until then feel free to send content to me directly. My email address is included in my profile.

[michael]

@Mohammad_Al_Hajj about the XSD files, one thing that I’ve found very helpful is by running

./gradlew setupIntellij

And opening the project in intellij configures all of the xsd files and allows for auto suggestions.

@Mohammad_Al_Hajj

Would you please consider adding concrete examples in the docs? I found it drastically quickened my learning time. My main problem in the past was finding the examples.

What is an example of a concrete example?

Everyone uses moqui in a different way, and so concrete examples are hard to define.

I found the Quick Tutorial for the example component very helpful initially.

@Mohammad_Al_Hajj

Would you also consider providing a standardized shape for the docs? For example, adding an example under each concept/“UI component”.

That’s certainly not a bad idea and I think it very well could be done that way. I’m currently working on actually getting anyone to be able to change the documentation.

[Mohammad_Al_Hajj]

@michael

./gradlew setupIntellij

And opening the project in intellij configures all of the xsd files and allows for auto suggestions.

I ran the task, but i am not sure what it does. Intellij already had autocomplete since i always copy in the root tag from an older file. It does that automatically as far as i know.

@michael

What is an example of a concrete example?

Example. A form-list can be created by explicitly defining its fields. It can also be filled using “auto-fields-entity”. Please note that auto-fields-entity will create an extra row to show the “total” of all number entries…possible solutions…talk about auto-columns=“false”
please refer to the below examples:
set every tag on a different line
set every attribute on a different line
use basic, non-technical, and easy to understand entities…not like i will be doing here
example 1: define the fields:

<form-list name="FLYearlyAccrual"
           list="accrualList"
           list-entry="accrual">
    <field name="partyRelationshipId">
        <default-field>
            <display-entity entity-name="mantle.humanres.employment.Employment"/>
        </default-field>
    </field>
    ...
</form-list>

example 2:

<form-list name="FLYearlyAccrual"
           list="accrualList"
           list-entry="accrual">
    <auto-fields-entity entity-name="erp.hr.payroll.BenefitFineTune"
                        auto-columns="false"
                        field-type="display"/>
    ...
</form-list>

@michael

I found the Quick Tutorial for the example component very helpful initially.

yes… initially… We need intermediate and advanced guides as well. These will honestly be the key for unlocking what we imagine moqui can do… I personally feel that moqui is useless outside of static, non-partially loadable screens (jQuery - i know about dynamic-container, but using it sucks both from initial understandability and forcing code split across files). I don’t know better, and i would love to see the example that proves me wrong.

With regards to advanced topics. My own example of one would be the process of using both client and server updating data in the same form and being able to reference them from each other. “depends-on” is cumbersome to use and not always available. I would love to open a new topic of why i think moqui, in its current ‘semi-static non-responsive’ UI building process and language (f*** xml), should not be widely adopted

Lastly, and following up on the last point, please try to give us the goals of the different ideas in moqui. I may be completely missing the point of what moqui is supposed to be.

sorry that that turned into a rant, but I detest moqui’s xml screens and how frustrating it is to refactor (ESPECIALLY MOVE!!!) code. possible solution? add “compile” time proofing" to it?

[michael]

@Mohammad_Al_Hajj If you don’t like the moqui xml screens you should be able to use just about any statically generated web framework without too much configuration / setup.

The xml screens are useful for doing cRUD operations, but if you want to get more technical and use more advanced vue, and possibly react or angular js frameworks you should be able to get them working.

The entities and data management that moqui uses is based on: https://www.amazon.com/Data-Model-Resource-Book-Vol/dp/0471380237

And that should help make the entities much more understandable.

@Mohammad_Al_Hajj You’ve pretty clearly done web development before. What frameworks / techniques did you use and what would you prefer to use in moqui?

[Mohammad_Al_Hajj]

@michael

The xml screens are useful for doing cRUD operations, but if you want to get more technical and use more advanced vue, and possibly react or angular js frameworks you should be able to get them working.

can you point me to an example code i can look at for reference?

@michael

The xml screens are useful for doing cRUD operations, but if you want to get more technical and use more advanced vue, and possibly react or angular js frameworks you should be able to get them working.

they are great for that

@michael

The entities and data management that moqui uses is based on: https://www.amazon.com/Data-Model-Resource-Book-Vol/dp/0471380237

And that should help make the entities much more understandable.

I will look at that book, thanks

@michael

@Mohammad_Al_Hajj You’ve pretty clearly done web development before. What frameworks / techniques did you use and what would you prefer to use in moqui?

Thank you for thinking that, but i was mainly a mobile developer (android, flutter) an i am currently back-end (or maybe fullstack? I do the screens too)… I dabbled with vanilla react a bit… But since i like statically scoped strongly typed languages i would love to try out flutter + moqui.

I am curious, is it possible to use java/flutter to completely replace xml screens? Can i simulate the lifecycle of moqui screens: always-action > pre-action > transition > action > widget using dynamic programming? Is it possible to do that without implementing web APIs as adapters (the same way moqui does it implicitly on screen creating time)?

[vince.clark]

@Mohammad_Al_Hajj , front end development is a a common theme that has come up in the community calls and pain points in this forum. So it is definitely a priority for documentation. I am not a front end developer so I am just trying to pull content together and give it some structure. But those with more experience will need to contribute the details. @doogie , your React experience would be helpful to include.
Some areas we should cover:

• Building screens using XML - Generally speaking I think xml screens are fine for internal CRM and ERP functionality but would like community input on this. Is there anything you cannot do with them that makes this a deal breaker?
• When to use other frameworks and how to use them with Moqui. Example use cases for when another framework was needed would be helpful and technically how it was done.
• How to best leverage what is already there. For example, Vue and Quasar are already in the code base. How can they be used independent of xml and does this address some / most of the use cases that would require another framework?
• Does it make sense to mix the approach, for example back office screens in xml and customer facing in another framework or is this too much overhead from a learning curve and code maintenance perspective?

Front end development is a skill set of its own, developers have their preferred tools and frameworks, and these are changing and evolving constantly. I am still learning but my sense is that Moqui is very flexible in this regard, we just need to surface and document how to use it.

[domiko]

Hi.

IMHO,
I personally think that the MakingAppsWithMoqui-1.0.pdf is particularly well written.
It dates back from 2014 so what I think what needs to happen is for it to be:

• Updated/upgraded to v3.0 of the framework
• Refreshed as some of the functionality of the time are not valid anymore (i.e. XML-RPC, intro of OpenSearch)

Obviously David is best suited to update the document since he wrote it in the first place. Others can certainly participate depending on their level of expertise.
The community should sponsor the effort or buy the copies when they’re made available.

Rgds.

[jonesde]

On the Making Apps with Moqui book: all of the content of that book is now on moqui.org in the documentation wiki spaces. Some parts of it has been updated more than other parts, like the Mantle data model diagrams and descriptions. It could use a general review.

Whether that is adequate for the needs and expectations others are presenting, I do not know but do not think so (especially for certain target audiences like end users… there are some docs there but very far from complete coverage of an app like Marble ERP).