Where to look documentation DOM manipulation for frappe?

Frappe Framework
1

I read the documentation and had hard time on where to look the syntax for DOM manipulation. There is the “$()” syntax and its seems JQuery. Any lead on where to learn this syntax? The documentation say something on “modern javascript” but nothing pops out related into the frontend frappe. Its lack a detail on this matter

2 Likes
2

$() usage is just vanilla jquery, nothing magical there. Check jQuery docs/tutorials.

3

@eisenhaus335 If you discover something, I’d love to know.

This frontend portion of ERPNext still feels very mysterious to me. I suspect the developers who wrote the JS portion of the Framework simply assumed that everyone else knew what they knew. :man_shrugging: Or they just ran out of time, and didn’t write any documentation or inline comments to explain.

I’ve never found anything that really explains how the framework hops around the DOM, and selects and manipulates things like grids, buttons, cells, sections, etc.

2 Likes
4

I don’t think the framework really intends for you to be manipulating the DOM directly. I mean, it’s javascript, so with a few monkey patches you can do whatever the heck you want, but all predefined front end structures like lists, forms, dialogs, reports, controls, etc. present much more abstracted apis: (i.e., Form Scripts )

If you need more direct control, your best bet is a custom page. There, you can define the DOM however you’d like and manipulate it with your choice of tools. Vue.js comes built in, but other interfaces could easily be added.

2 Likes
5

I agree

ERPNext documentation is good. But, there is no much good tutorial on how to really understand the frappe. I think many tutorials (from official to community) are focused to provide ERP experience but forget to address the frappe where us as the programmers that doing our things. I hope they address frappe more with doing basic project to-do application with frappe

I forget to put what i want with the frontend. I wanted to make some kind forms like point of sales ones. But, there is just no documentation or blog that explain how they make point of sales forms

2 Likes
6

You would use the Page API, which is documented here: Page API

Once a page is created, you can roll out any any arbitrary html you’d like.

7

To help illustrate the challenges some of us face, I’m going to use this thread as an opportunity.

Let’s Dissect Page API

(Please Note: I’ve tried to be careful with my words below. I don’t want to exaggerate or be overdramatic. This is my serious and thoughtful “take” on the documentation.)

  1. The documentation begins talking about 'frappe.ui.Page'
    What is a “Page”? This is not clear to me. It’s definitely a JavaScript object. Beyond that, I don’t know. There is no introduction or context.

    • What is special about the Page object? Can I use them to create new web pages, like in the ‘www’ folder? Can they be used for modifying existing DocType pages? All of the above?

( I’m 95% certain this has nothing to do with the similarly named 'Web Page' feature of Frappe, nor the semi-deprecated Portals.)

  1. Where does one write JS code for a “Page”? In an existing Document’s JS file? Or do you have to create a new file somewhere?

  2. Must a Page object exist inside the scope of other JS objects we typically encounter, like 'frappe.ui.form.on('Customer')?

  3. The documentation says you can create a new page and “attaches it to parent.”

    • What exactly is a “parent” in this context?

    • Examining the screenshot of a code block, a “parent” is also a wrapper? Which is an HTML DOM Element or jQuery object. Okay. So how do you obtain a reference to such a thing?

  4. These next methods were reasonably self-explanatory to me:

    • page.set_title
    • page.set_title_sub
    • page.set_indicator
    • page.clear_indicator

  5. Next, page.set_primary_action kind of made sense. But leaves a ton of questions unanswered for me:

    • Does that variable declaration and assignment let $btn = ... require the JQuery dollar sign at the front? No idea why that’s important.

    • What other icons can I use, besides this “octicon”? Searching the web, I “think” they’re coming from Octicons • Iconify? I could be wrong, though. Does Frappe ship with the entire set of those, or just a subset?

  6. No questions about page.clear_primary_action or page.set_secondary_action, that haven’t been addressed above.

  7. The methods below make sense to me. But that’s because I’ve worked with them before, while editing DocType JS files.

    • page.add_menu_item
    • page.clear_menu
    • page.clear_actions_menu
    • page.add_inner_button

  8. I have zero idea what 'change_inner_button_type’ is trying to accomplish. What does it even mean by “type”? There should be some additional screenshots, or explanation of “type” here.

  9. No questions with 'page.remove_inner_button()' and 'page.clear_inner_toolbar()'

  10. However, page.add_field. I can think of many questions.

    • How do I reposition this “field” around on the page? If the answer is CSS, where do I write it? Also, how would I reference my new “field” in CSS?

    • Pretty sure there’s no database behind this field. It’s not a DocField, it’s just a web page object. So it’s going to get lost if I refresh. But what if I -want- to store my data field somewhere? How can I accomplish this the way the Framework would want me to? Can I link this to a DocField? Am I forced to read or write to DocTypes directly on my own?

    • Is that “change()” method the only method available for these “fields”? If not, what else is available?

  11. Finally, for 'page.get_form_values()' the documentation says “Get all form values from the page form toolbar in an object.”

    • I’ve re-read that sentence 4 times, and still don’t understand it.

Conclusion

Having now re-read this documentation at least 3 times, I’ve learned nothing I can apply in the real world. Somewhere, there is some missing context that I simply don’t have.

I could search around in the Frappe and ERPNext repositories. Examine what the maintainers have written. And through some trial and error, perhaps understand these “Pages”.

(this is the method I’ve used to learn 95% of what I know about ERPNext. it’s not ideal, but it eventually worked.)

Still, that’s not what the OP asked for. They read the documentation, and like me, found it lacking. And were hoping that somewhere on the World Wide Web, there was a more in-depth explanation.

Going to stop now, because this post is long enough already. But suffice to say I have dozens of other questions about JQuery, grid manipulation, Vue, displaying hidden fields, and much more. All just as sparsely documented (imo).

4 Likes
8

almost the same approach to learn and hack Frappe/ERPNext for me, source code is always the most comprehensive and correct documentation anyway.

maybe we can try to contribute to the documentation little by little.

2 Likes
9

It’s all a lot less complicated than how you’re thinking about it. The first line in the docs says the important part:

Every screen inside the Desk is rendered inside a frappe.ui.Page object.

So we’re not talking about portal pages, and we’re definitely not talking about anything scoped inside a form’s event triggers like frappe.ui.form.on('Customer'). The form view itself is a frappe.ui.Page object.

When you create a new Page doc, frappe automatically generates boilerplate code in the module folder you designate. The JS file looks like this:

frappe.pages['fun-page'].on_page_load = function(wrapper) {
	var page = frappe.ui.make_app_page({
		parent: wrapper,
		title: 'None',
		single_column: true
	});
}

From there, you can use the methods outlined in the API documentation, or you can manipulate the DOM directly using whatever frontend technology you prefer. Vue and jquery come built in, but any client-side library should work if you import it. Vanilla js works too of course.

3 Likes
10

Frappe don’t explain how massively different they are than other framework. If you compare like regular framework, they have limited scope on what they doing. But, frappe have too many functionality and it increase the learning curve. I just stressed out by the scope. Like you have desk then form, then page and many little details that’s very abstract but just too specific to miss out. Even Victoria 2 are not that difficult. It might just me that pay too much details, but the documentation page don’t limit me. I don’t know how to tackle this. I think separated important documentation and tutorials page is good? Like svelte or rust where they have separated page

Also, regarding the scope. Frappe is very abstracted framework looking on programming side. Like they have this Form, Desk, Page, List, etc. I confused what they each used for. The tutorial explained them but in very ‘user-experienced’ way to explore. I took many times to realize this. Only by seeing youtube creator open command console and see how they interact. But, the problem persist its still hard to understand what tutorials intend us to do. I don’t learn by doing it and only read every much details i could

I also realized there is two world to see frappe. That involved CMS and other was on your IDE. The way tutorial written are doing it with only the CMS. So, what our IDE used for. There is no illustration on this regard. Ok, we can look on youtube and so on. You now then overwhelemed with very limited abstract understanding and need to watch way how the youtuber doing it and still you are not understand any of that. See how them do this and that. I still can’t figure out what form, desk, page used for. This is problem with how learning by doing, there is not much context on the abstract (or what the creator system way to do). The learning base are just very fragmented with no ‘good’ fundamental video. Its like learning wordpress or gatsby

I hope there is focus to create just that one ‘good’ tutorial, the first tutorial has too much lack in details and the fundamentals. Then, write a maybe definitive guide to understanding frappe concept. There is just too many fragmented idea scattered throughout the documentation

I think the team don’t have much input from newcomer and it cause this huge learning curve. Maybe doing survey will be good. There is no structure like curriculum i think on when they write the tutorial. The way “learning by doing” from the tutorial is kinda too microing the user, I think idk. Ok thats maybe all my concern. Thank you for the time being

3 Likes
11

I agree; there’s no great “big picture” overview of the framework from a technical perspective. It’d be a lovely thing to have.

I wouldn’t underestimate how difficult it is to write something like that well, but it’d be a great way for the community to contribute.