User Tools

Site Tools


script

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
script [2014/01/15 04:06]
l [prerender and postrender]
script [2014/09/29 12:33]
ateyourlembas
Line 1: Line 1:
 +<- [[stylesheet|Changing Your Story'​s Appearance]] --------- [[custom_macro|Writing Your Own Macros]]->​
 +
 ===== Scripts ===== ===== Scripts =====
  
-Just as you can tag a passage ''​stylesheet''​ to have its contents treated as CSS style rules, you can use the ''​script''​ tag to include custom Javascript in your story. All passages ​with this tag are executed when the page loads, which you can use as an opportunity to do two things:+Just as you can tag a passage ''​[[stylesheet]]''​ to have its contents treated as CSS style rules, you can use the ''​script'' ​[[tag]] to include custom Javascript in your story. All [[passage]]s ​with this tag are executed when the game first loads, which you can use as an opportunity to do two things:
  
-  * Install custom ​[[macro]]s made in Javascript by other Twine users. +  * Define ​[[custom ​macro]]s made in Javascript by other Twine users. 
-  * Modify how your story will work. To do this properly requires careful inspection of the Twine engine.+  * Modify how the Twine engine ​will work. To do this properly requires careful inspection of the Twine engine.
  
 The execution order of passages tagged ''​script''​ is based on the alphabetical order of the script passages'​ names. The execution order of passages tagged ''​script''​ is based on the alphabetical order of the script passages'​ names.
 +
 +**Remember:​** script passages must //only// contain Javascript.
 +
 +
 +====Coding in Twine==
 +
 +  * More details about coding in Twine can be found under [[code|Why Use Code]]?
 +  * Other common questions are handled in the [[frequently_asked_questions|FAQ]].
 +
  
 ====Requesting jQuery==== ====Requesting jQuery====
  
-You may wish to use [[http://​jquery.com|jQuery]] in your scripts to manipulate the page's structure. But, you want other people to be able to use your script without having to set the [[StorySettings]] jQuery value themselves. There is another way to request jQuery: simply put the case-insensitive words "​requires jQuery"​ in a comment or a string inside your code:+You may wish to use [[http://​jquery.com|jQuery]] in your scripts to manipulate the page's structure, use AJAX, or just make general coding easier. But, you may also want other people to be able to use your script without having to set the [[StorySettings]] jQuery value themselves. There is another way for a story to request jQuery: simply put the case-insensitive words "​requires jQuery"​ in a comment or a string inside your code:
 <​code>//​requires jquery</​code>​ <​code>//​requires jquery</​code>​
 You can also request the [[http://​modernizr.com|Modernizr]] library with the words "​requires Modernizr"​. You can also request the [[http://​modernizr.com|Modernizr]] library with the words "​requires Modernizr"​.
  
 +A reminder: you do **not** need to call ''​$.noConflict()''​ when you first invoke jQuery in Twine 1.4 or higher.
 ====prerender and postrender==== ====prerender and postrender====
  
-Two objects exist in the Twine engine that are designed for custom script writers: ''​prerender''​ and ''​postrender''​. If you add Javascript function ​property ​to these objects, ​that function ​property ​will be run every time a [[passage]] is rendered.+Two objects exist in the Twine engine that are designed for custom script writers: ''​prerender''​ and ''​postrender''​. If you add Javascript function ​properties ​to these objects, ​those function ​properties ​will be run every time a [[passage]] is rendered.
  
-A ''​postrender''​ function looks like this:+A ''​postrender''​ function looks something ​like this:
 <​code>​ <​code>​
 postrender.hello = function(a) { postrender.hello = function(a) {
-    a.className += "​hello";​ +    ​... 
-    console.log(this.title);​  +    ​a.className += "​hello"; ​// An example of '​a'​ 
-}</​code>​ +    console.log(this.title); ​// An example of '​this'​ 
-When ''​postrender.hello''​ is called, ''​this''​ is the Passage object which is currently being rendered, and the first argument ''​a''​ is the <div class="​body content">​ element into which the passage'​s code has been rendered. You can thus transform or modify the div's contents in interesting ways.+    ... 
 +};</​code>​ 
 +When ''​postrender.hello''​ is called, ''​this''​ is the Passage object which is currently being rendered, and the first argument ''​a''​ is the ''​<div class="​body content">​'' ​element into which the passage'​s code has been rendered. You can thus transform or modify the div's contents in interesting ways.
  
-''​postrender'' ​is called just after the passage'​s code is renered ​into the div. ''​prerender'' ​is called just before then.+''​postrender'' ​functions are called just after the passage'​s code is rendered ​into the div. ''​prerender'' ​functions are called just before then.
  
 ===Passage objects=== ===Passage objects===
 Passage objects have the following structure (plus some other less useful properties):​ Passage objects have the following structure (plus some other less useful properties):​
->title: the string name of the passage. +  * title: the string name of the passage. 
->tags: an array of strings representing the passage'​s [[tag]]s. +  ​* ​tags: an array of strings representing the passage'​s [[tag]]s. 
->text: the raw code of the passage. +  ​* ​text: the raw code of the passage. 
->processText():​ the code of the passage with some substitutions made - the "​nobr"​ tag, if present, removes line breaks, and imported [[image]] syntax has the image'​s base64 data inserted.+  ​* ​processText():​ the code of the passage with some substitutions made - the "​nobr"​ tag, if present, removes line breaks, and imported [[image]] syntax has the image'​s base64 data inserted.
  
 ====Collisions==== ====Collisions====
  
 If you use a lot of scripts from many people, note that as of 1.4.1, naming collisions in the ''​macros'',​ ''​postrender''​ and ''​prerender''​ objects (such as, adding macros which have the same name) are not alerted to the author. Take care that each addition to these objects has a unique name. If you use a lot of scripts from many people, note that as of 1.4.1, naming collisions in the ''​macros'',​ ''​postrender''​ and ''​prerender''​ objects (such as, adding macros which have the same name) are not alerted to the author. Take care that each addition to these objects has a unique name.
 +
 +<- [[stylesheet|Changing Your Story'​s Appearance]] --------- [[custom_macro|Writing Your Own Macros]]->​
script.txt · Last modified: 2017/10/09 20:39 (external edit)