Introduce b.addToText(), discontinue b.addToStory()

[trych]

Apart from the fact that b.addToStory() does not work at the moment ( #71 ) , I think it could also improved structurally. This was mentioned in another issue ( #44 ), so I will mostly copy/paste to this issue here.

I think the method could become more "basil like" beginner friendly, if it was changed in these ways:

1) Skip the requirement to have a story object instance as input. It is quite difficult to retrieve a specific story object within the basil.js universe and I guess many beginners don't know what a story actually is. How it could work instead: Allow textFrames as input. textFrames are a whole lot easier to address in basil.js and a much easier and much less concept for beginners. The new texts could be added at the beginning at the end or somewhere within the textFrame. Should text then move to the next linked textFrame or into overset text, it will be obvious. Additionally we could allow paragraphs, lines, words, characters (and yes, why not, stories) as input. This could also be convenient, if you found a word already then you could easily just add text to it. So the whole method rather becomes a "b.addToText()" (and should be renamed accordingly) and easier to use, I think.

2) Instead of an insertionPoint as input I would also allow for a simple index. Same as with stories, there is no way in basil to retrieve an insertionPoint (or is there?) and beginners don't know what an insertionPoint is (let alone that it is an object, not a "index like" position). So if we give the option to use a simple number as index, I think it would be also much easier for beginners.

And we could also include the "add in certain (paragraph|character) style" feature that @b-g proposed in #44.

So the specific method would be:

b.addText({textframe|story|paragraph|line|word|character}, text, [index|insertionPoint|b.AT_BEGINNING|b.AT_END],[characterStyle|paragraphStyle] )

If others like the idea, too, the question is, if we should then discontinue the b.addToStory() method. Usually I would be all for staying backwards compatible, but this feature has not been working for almost three years now (does not work in 1.08), so I think we could take it out of the official reference and replace it by b.addToText().

We could still leave a b.addToStory method in the code that throws a basil.js warning: b.addToStory(), this method is deprecated. Please use b.addToText() instead. Or simply let the b.addToStory() method run the b.addToText() method (as it is compatible regarding the inputs).

Please flag as enhancement and feature.

[trych]

@b-g: As you started the discussion about the »addToStory with styles« initially, I would like to hear your opinion on my suggestion to introduce »addToText()« and discontinue »addToStory()« (see my explanations above).

If you approve, I would assign myself to this issue and start to work on this. At the moment the method is not working at all anyways, so something needs to be done.

[b-g]

Hi @trych,

Sorry for the radio silence! The proposed b.addText({textframe|story|paragraph|line|word|character}, text, [index|insertionPoint|b.AT_BEGINNING|b.AT_END],[characterStyle|paragraphStyle] ) sounds great! Please go ahead as proposed!

Good would be if addText() returns the text for easy styling e.g.

var t = b.text("hello", 0,0 , 100,100);
var text = b.addText(t, " world", b.AT_END);
b.typo(text, "pointsize", 30); // only "world" is set to 30

[trych]

Great!

Good would be if addText() returns the text for easy styling e.g.

Good idea, will include this.

[trych]

@b-g As we now have b.applyParagraphStyle() and b.applyCharacterStyle(), I would vote to not include the optional paragraphStyle|characterStyle argument in the b.addToText() function, as we now simply could do

b.applyCharacterStyle( b.addToText( myTextFrame, "my text" ), myCharStyle);

to apply a style to the added text. This would keep b.addToText() cleaner and make it only about adding text.

What do you think?

[b-g]

@trych super! +1 for

b.applyCharacterStyle( b.addToText( myTextFrame, "my text" ), myCharStyle);

Side note: I guess the only missing function in that realm is then something like b.story(obj) to extract the related story from e.g. a text frame. Could also be that b.stories does already the trick ...

[trych]

Yes, we should use b.stories() to retrieve the parentStory of a textFrame. Technically (although undocumented) you can also retrieve the "parent" paragraph of a character by doing b.paragraphs(myCharacter), so b.stories() should work the same.

And another side note: a text object that is still missing is textStyleRange(), so I would vote to also introduce b.textStyleRanges().

[b-g]

hi @trych

+1 to b.stories() and better documentation ... or maybe better b.parentStory(obj, [cb])?

Can you elaborate what do you mean with b.textStyleRanges()? Not 100% sure what you mean with it.

Cheers, B

[trych]

hi @b-g

+1 to b.stories() and better documentation ... or maybe better b.parentStory(obj, [cb])?

No, I think b.stories() fits pretty well, as it will go nicely with b.words() and so on and can serve for more than one purpose (get story of text frame, get stories of page, get stories of doc). The documentation is fine, I think. At the moments the docs only name the parent containers to iterate the current item in. I think to also name the child containers would cause more confusion than it helps. Still, the functionality is there, as it would be more effort to exclude it and it does not do anybody any harm.

Can you elaborate what do you mean with b.textStyleRanges()? Not 100% sure what you mean with it.

In ExtendScript a textStyleRange is another InDesign text class, just like words, paragraphs or lines. A textStyleRange describes a range of text with the same style. So the following text snippet is divided in three text style ranges:

It can be quite useful to return these textStyleRanges, so I think we should also include it as b.textStyleRanges(item, [cb]).

[b-g]

@trych thanks for the explanation + wasn't aware of this ...
+1 for b.textStyleRanges(item, [cb])