Doc Improvement - Example on how to update a blot

[ergo]

Hi,
The chapter https://quilljs.com/guides/cloning-medium-with-parchment/ is really great and helpful.

One thing I'm missing a lot is an example on how to implement a custom blot that would allow customizing some properties like image width/height or maybe video tag url.

Even using a simple prompt() example for that would be great. I think it would also help reduce the amount of questions on image resizing etc.

[jhchen]

Quill allows you to define arbitrary formats so covering every single case with an example is not possible. But what we can do is cover common cases and principles to allow users to build upon and extrapolate.

allow customizing some properties like image width/height or maybe video tag url.

The video section of the guide you linked includes an example that customizes the width/height. A similar approach can be taken with images. I'm not sure what you mean by video tag url in the context of that sentence.

Even using a simple prompt() example for that would be great

The examples in the guide use something even simpler: hardcoded values. Quill's API, like most APIs, does not care how you got the values it is passed. It could be a static value, a prompt() call, or a fancy responsive reactive UI.

[ergo]

Hey, maybe I wasn't clear on what I wanted to ask about, I understand how to create a new custom blot and insert it. I'm not sure how to "edit" existing blot in the document.

I would love to see an example that would show how to edit src of image using prompt() with onclick handler.

A common use case would be to edit image sizes or replace image with another one - I can implement the UI for that as this is out of the scope of quill (I got the impression that features like are not intended to get ever implemented in quilljs from other tickets), I'm not sure how to get the right range on click and how to update the delta properly with new values.

I looked at the docs and I wasn't able to find any example on how to do this.

[ergo]

Any update on this? Any example on how to update attributes of an embed blot would be great.

[jhchen]

If you have a reference to the blot, you can just call format on it. Quill will figure out what happened through mutation observers and fire the appropriate text-change event.

You can also get a reference to a blot from a DOM node from Parchment.find(), which should be available in a DOM event handler.

If you want to find where the blot is for some other reason (insert something before the image), you can use offset(). The root scroll blot is accessible from quill.scroll (though this is variable naming/access subject to change) so you can do myBlot.offset(quill.scroll) if you want it relative to the entire document.

[ergo]

Awesome, I think this is exactly what I'm looking for - I'll try to figure this on my own.
If in the future chapter https://quilljs.com/guides/cloning-medium-with-parchment/ would be update with an example it would be great!

[rikh42]

Would be cool to add a way to do the equivalent of myBlot.offset(quill.scroll) that does not depend on knowing about quill.scroll, as I use this quite a lot.

[jhchen]

I agree exposing offset more easily would be helpful. I have to think a bit more about the right interface since Quill is under semver, I don't have to live with a suboptimal API or having a major version bump. I'm not sure there's anything else actionable with this issue.

[ergo]

So as i understand to get this to work one needs to use API's from both quill and parchment. Do you think an example in the docs could be added? That would hopefully reduce the number of issues opened to ask questions on how to archive this functionality. Right now browsing issue tracker as an alternative to FAQ seems like waste of dev team resources because the question i think was posted multiple times in different forms and we have to gather information from multiple tickets to get something meaningful out of this.

Since this ticket was closed as "unactionable" I assume the docs will not be expanded?

[jhchen]

There are lots of ways to get width formatting to work, depending on how you defined the Blot, and what references you have. Alternative ways do not involve custom Blot, since the core Quill image blot already recognizes width and height, or Blots at all, since you can also use Attributors. As I already said examples for every single case is not attainable nor effective.

Quill is a very popular project and gets a lot of questions about everything. The other issues related to image width or resizing were either duplicates (immediately marked and closed as such) or desiring a UI, which is not on the foreseeable roadmap (which I have stated in the relevant issue).

This Issue's main question as filed was "how to implement a custom blot that would allow customizing some properties like image width/height". There is already an identical video example for that. It is evident now your actual question was closer to "how do I format a blot with a custom format that supports it" which has an exact API for that purpose aptly named format. If you want to use Parchment in Quill, which is the purpose of the guide linked, I believe it is reasonable to be aware of both libraries' APIs.

The distinction between the two forms of your question is a bit pedantic, but that was all the information you provided. There was no elaboration in the form of words or code, or details about what you already tried or were trying. Providing as much information and clarity as you can also goes a long way in getting more out of open source communities. Etiquette such as following the Contributing Guidelines will also get you more mileage. Generally this sort of Issue as judged by the original post have been auto-closed as it does not follow the guidelines.

Of course documentation in general could always be improved but that is an ongoing process and Issues is for specific purposes and your two questions are answered so I considered the specific purpose of this Issue resolved. There will be more guides and examples on using Parchment. That might be a followup or continuation of the Medium guide, it may be a separate guide, or even creation/change to Parchment to make it more intuitive.

I know a lot of other open source projects leave open hundreds of issues forever mentally marking them as "someday maybes" or go on long tangents within an Issue thread but I prefer to be more realistic and streamlined with Quill.

[ergo]

This Issue's main question as filed was "how to implement a custom blot that would allow customizing some properties like image width/height". There is already an identical video example for that.

Can you point me to an example of that?

All i could find is an example of how to insert a video blot- there are no examples on how to actually edit (any) attribute (iframe src?) of a blot that already exists in the document (I'm aware that requires custom UI implemented, this is why i asked for something that would be implementable with prompt() to make it easiest, width being an example here). Maybe I'm not seeing something obvious here.

I'm sorry - my question was not precise enough and i blurred the actual question - I'm not a native speaker.

The part of API that is used for marking elements for editing is unclear for me - if that makes more sense.

The list of things to implement would be something like:

• add an onclick hander
• use the event target to localize clicked blot
• call quill.format() with new properties

The problem is that I got confued a bit - I got an impression that i have to call format on blot, yet quill seems to format the currently selection range, also do i need to somehow update selection range first?

This is why i asked for any example of how to manipulate any property of an existing blot in the document (that was the intended purpose of this issue).

[whatcould]

I think I had the same question as @ergo. The issue I had was not, how to update the format(s), but how to update the properties used to create the blot — the object you get back from blot.value(), aka the object you send to create a new blot/node.

For what it's worth, digging through the Parchment source I couldn't find a suitable method. I ended up using blot.replaceWith which just replaces the entire node. Eg, if you are trying to update the URL on an image: imageBlot.replaceWith("image", "http://example.com/new-image.jpg");

If your blot has an object as its value (with multiple properties, as opposed to a string), or has useful formatting/class names/etc, you'll have to do some work to only update the properties you want.

[themsaid]

@whatcould There need to be some documentation on this, being able to update the blot by updating the values is a great win.