add to story with styles

[ff6347]

@b-g mentioned that there is no way to add something into a story. Please it a little bit more

[b-g]

I meant in addition to b.addToStory I often endend up having to writer helper functions, for being able to add things in a formated way to a story.

function addToStoryWithCharStyle(story, content, charStyle) {
  var oldCharLength = story.characters.length;
  b.addToStory(story, content);
  for (var i = oldCharLength; i < story.characters.length; i++) {
    story.characters[i].appliedCharacterStyle = charStyle;
  };
}

addToStoryWithCharStyle(story, headerText, "Precious Serif Head");
addToStoryWithCharStyle(story, bodyText+"\r", "None");

[ff6347]

Okay. I get it. One thing about the function you wrote.
Using loops to set a characterStyle or editing characters at all can take a long time. I think using the functions like everyItem(), or itemByRange() that the IDAPI provides is way faster.
I wrote a tost to compare those two approaches.

Using the loop takes 0.5 to 0.9 seconds
Using the itemByRange takes between 0.006 and 0.04 seconds. (I can't tell why the range is so huge)

    function Timer() {
      var started = null;
      var stopped = null;
      this.start = function() {
        started = new Date();
      };
      this.stop = function() {
        stopped = new Date();
        var timetaken = (stopped.getTime() - started.getTime()) / 1000;
        return timetaken;
      };
    }

var useAPIfunctions = true;
var d = app.documents.add();
var p = d.pages[0];
p.textFrames.add({
    geometricBounds:[0,0, d.documentPreferences.pageHeight, d.documentPreferences.pageWidth]
  });
var s = d.stories[0];
var str = "Lorem ipsum dolor sit amet, consectetur adipisicing elit,"+
" sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis"+
" nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure"+
" dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur"+
" sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
var lastindex  = s.characters.length;
var cstyle = d.characterStyles.add({
    fillColor:d.swatches[5]
  });
// ------
if(useAPIfunctions === true){
// using IDAPI functions inner 
var duration1 = new Timer();
duration1.start();
s.insertionPoints.lastItem().contents = str;
var newlastindex =  s.characters.lastItem().index;
var txt = s.characters.itemByRange(lastindex + 1 ,newlastindex ).applyCharacterStyle(cstyle);
$.writeln("itemByRange took: " + duration1.stop());
//------
}else{
// using for loop  
var duration2 = new Timer();
duration2.start();
s.insertionPoints.lastItem().contents = str;
  for (var i = lastindex ; i < s.characters.length; i++) {
    s.characters[i].appliedCharacterStyle = cstyle;
  };
$.writeln("for loop took: " + duration2.stop());
}

[b-g]

Cool + WOW!

I guess then there would be a lot of performance boost low hanging fruits in the basil core, as we almost never use this "better" way for manipulating the indesign doc e.g. everyItem(), itemByRange().

[ff6347]

I'll create an issue for that.

[trych]

Since we are touching this anyway, two further ideas to improve this method and make it more "basil like" and beginner friendly:

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 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 easier to use, I think.

2) Instead of an insertionPoint as input I would use 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 have an index instead (and still allow b.AT_BEGINNING and b.AT_END), I think it would be also easier for beginners.

I remember when I started out, I had no idea how to use this method, although now I know it's super useful.

@fabiantheblind, @b-g , what do you think?

[trych]

That aside, I don't get the method to work at all at the moment.

Could somebody test this snippet for me and tell me, if it works? Does not do anything for me…

#includepath "~/Documents/;%USERPROFILE%Documents";
#include "basiljs/bundle/basil.js";

function draw() {
  var tf = b.text("This script …", 0, 0, 200, 200);
  var story = tf.parentStory;

  b.addToStory(story, " works!");
}

b.go();

Is it just me or is this broken in general?

[ff6347]

Nope. Does not work for me in CS6. Sounds like there is a lot of stuff broken. Needs an issue for each I think.

[ff6347]

I'm not sure about the switch to the index but I like the idea of having a b.addText(tf, story, words, line). Could still have the parameter for the character or paragraph style so it would be:

b.addText({word, line, paragraph,textFrame, story},[index, insertionPoint, beginning, end],[characterStyle, paragraphStyle] ) 

[ff6347]

Tested the script in CC2015 and CC2014 on OSX 10.11.5 does not work. :-(

#includepath "~/Documents/;%USERPROFILE%Documents";
#include "basiljs/bundle/basil.js";

function draw() {
  var tf = b.text("This script …", 0, 0, 200, 200);
  var story = tf.parentStory;

  b.addToStory(story, " works!");
}

b.go();

[trych]

b.addText({word, line, paragraph,textFrame, story},[index, insertionPoint, beginning, end],[characterStyle, paragraphStyle] )

This would be great I think, and yes, of course we can also allow an insertionPoint.

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).

I will create an issue for this.

[ff6347]

I would go for the warning. It still is a tool for education. I also think we should not leave a broken method in there.