SugarCube 2: Best practice for altering HTML?

JordanMagnuson

Here's the setup: I want my story to have large background images that cover the browser window (as seen here). Simple to do with css: give body.mypassage a background-image with "background-size: cover;" and voila. But the twist is that I want to be able to fade these background images in and out with particular timings, using javascript: the background-image property itself can't be faded with javascript (as far as I know), and fading out document.body doesn't tend to work very well .

So what I'm thinking to do is just create a "backgroundmask" div immediately inside body with absolute positioning and width and height set to 100%. That should cover the full screen as desired, and I can mess around and change that div's background-image, and fade it in and out at will.

Assuming that's the best way to approach this problem (which it may not be), my question is: how should I go about adding this new div to the dom? I see SugarCube 2's HTML structure here, and I feel like there should be a template or something to allow for editing the basic structure... but maybe I'm wrong? Should this kind of html modification simply be handled in javascript in prerender, or one of SugarCube's other task objects?

Thanks in advance for any help!

[Shoot: meant to post this as a Question rather than a Discussion]

greyelf

You can use Javascript code like the following to add an HTML element to the document body, the code needs to be placed within a script tagged passage.
If your story does not have a script tagged passage yet then you can use the Story > New > Script menu items to create it.

$('<div id="background"></div>').appendTo(document.body);

You can use CSS to position the element but remember to set its z-index property to a negative number so that it appear behind everything else.

You can use code like the following in a passage to add the image to be displayed:

<<replace "#background">><img src="backgroundA.jpg"><</replace>>

I will leave the transition CSS to you.

JordanMagnuson

Thanks for the help, greyelf!

Is it best practice to do something like this in StoryInit or another of SugarCube's special passages/task objects... or to just put it in any 'script' tagged passage?

When will scripts in any 'script' tagged passages get executed relative to scripts that are placed in StoryInit, PassageReady, PassageDone, etc.?

greyelf

Generally it is a good idea to only have a single script tagged passage in your story because you can't control the order multiple script tag passages will be processed in, which can result in errors if the code in one script relies on the code in another. The same is true for stylesheet tagged passages.

I would generally place Javascript that initializes/configures/extends a story's environment within in a script tagged passage.

TheMadExile would be the best person to answer your question about the process order of the different types of event/passages but the following can either be observed via testing or read about in the documentation of things like Task Objects

a. The contents of a script must be processed before StoryInit because you can use things (like macros) defined in the script within the StoryInit.

b. The contents of StoryInit is processed before the p__display / p__render related events or the equivalent PassageReady / PassageDone special passages.

c. The process order of the p__display / p__render related events or the equivalent PassageReady / PassageDone special passages is documented in the Task Objects link.

JordanMagnuson

Thanks, that's helpful!

Is it possible to access and alter the current passage text from a script tagged passage before that text is rendered (i.e. before Twine-style links get turned into actual html links, etc.)?

TheMadExile

JordanMagnuson wrote: »

Is it best practice to do something like this in StoryInit or another of SugarCube's special passages/task objects... or to just put it in any 'script' tagged passage?

For a once-off addition to the DOM, like your background <div>, it would be best to place it within a script-tagged passage (or Story JavaScript, for Twine 2 users).

JordanMagnuson wrote: »

When will scripts in any 'script' tagged passages get executed relative to scripts that are placed in StoryInit, PassageReady, PassageDone, etc.?

During initialization: (in order)

1. script-tagged passages (or Story JavaScript, for Twine 2 users)
2. StoryInit special passage

During normal operation: (in order)

1. prehistory task callbacks
2. predisplay task callbacks
3. PassageReady special passage
4. prerender task callbacks
5. PassageHeader special passage
6. PassageFooter special passage
7. postrender task callbacks
8. PassageDone special passage
9. postdisplay task callbacks

JordanMagnuson wrote: »

Is it possible to access and alter the current passage text from a script tagged passage before that text is rendered (i.e. before Twine-style links get turned into actual html links, etc.)?

As answered in your other thread. Not really, no. If at all possible, you should be trying to use the standard mechanisms (i.e. macros and $variables).

JordanMagnuson

Thanks, TheMadExile. I did catch most of the "During normal operation" order from the SugarCube documentation, but did not manage to find the info about script-tagged passages getting processed first-thing during initialization... that all makes sense.