Molecular Playground/Authoring: Difference between revisions

← Older edit

Proteopedia Page Contributors and Editors (what is this?)Proteopedia Page Contributors and Editors (what is this?)

Eric Martz, Craig T Martin

@@ Line 29: / Line 29: @@
 ===Facilitate rotation by onlookers===
-MP invites onlookers to interact by rotating the structure at any time. Therefore, scripts should be designed to permit rotation as much of the time as possible. Furthermore, it may be desirable for the user-set orientation to remain while the script proceeds, perhaps all the way to the end of the script. For example, a ''moveto'' command precludes rotation until the specified orientation is completed. In the version of Jmol currently used in Proteopedia (11.8.9 in December, 2009), ''zoomto'' commands also enforce the current orientation, "fighting" with the onlooker who attempts rotation during the timed zoomto. Therefore, the support script provided for MP includes a function ''zoomRotatableTo()'' that performs the zoom while permitting rotation.
+MP invites onlookers to interact by rotating the structure at any time. Therefore, scripts should be designed to permit rotation as much of the time as possible. Furthermore, it may be desirable for the onlooker-set orientation to remain while the script proceeds, perhaps all the way to the end of the script. One command that goes counter to this goal is a ''moveto'' command, which precludes rotation until the specified orientation is completed. In the version of Jmol currently used in Proteopedia (11.8.9 in December, 2009), ''zoomto'' commands also enforce the current orientation, "fighting" with the onlooker who attempts rotation during the timed zoomto. Therefore, the support script provided for MP includes a function ''zoomRotatableTo()'' that performs the zoom while permitting rotation.
 ===Avoid displays that seriously slow Jmol===
@@ Line 52: / Line 52: @@
 ===Three Levels===
-Three levels of scripting are available for creating modules for MP.
+Three levels of scripting are available for creating modules for MP. Each is described below, and examples are shown.
-*
-*
-*
 ===Level I: A single script file===
-This is the '''quickest and easiest''' way to prepare a module for MP. It will lack any color keys or text, other than a banner at the top. It will be a '''single customized molecular scene, spinning''', without any transitions or animation. If you later decide that you want to add a color key, it is straightforward to reconfigure your Level I script into a Level II module.
+This is the '''quickest and easiest''' way to prepare a module for MP. It will be a '''single customized molecular scene, spinning''', without any transitions or animation. It may include labels on specific atoms, but will lack a color key. If you later decide that you want to add a color key, it is straightforward to reconfigure your Level I script into a Level II module. An <font color="red">example</font> of how a Level I module will look when projected in MP is seen below when you press the <font color="red">''Add Banner''</font> button in the next section.
-An MP module at Level I consists of three items that will be submitted to [http://molecularplayground.org the MP team].
+An MP module at Level I consists of two files plus two pieces of information that will be submitted to [http://molecularplayground.org the MP team]. The first three below are required in your initial submission.
-# A single file of Jmol script commands that specifies a single molecular scene.
+# A single file of Jmol script commands that specifies a single molecular scene (the "state script").
 # A [[PDB file]] that provides the molecular model displayed by the script.
 # A banner title, which should be of length 65 characters or less.
+# The URL of your "more information" web page (see [[#Web Page Procedure in Proteopedia]]). If your web page is not yet ready, this can be submitted later.
 There are two ways to prepare the script file.
-* By hand. This requires familiarity with the [http://chemapps.stolaf.edu/jmol/docs/ Jmol Command Scripting Language]. No instructions are provided here for this method, either for constructing the script file, or for making a supporting web page.
+* '''Recommended:''' In Proteopedia, using its [[SAT|Molecular Scene Authoring Tool]]. You don't need to be familiar with Jmol command scripting language. You save the "state script" from Jmol in Proteopedia.
-* In Proteopedia, using its [[SAT|Molecular Scene Authoring Tool]]. You don't need to be familiar with Jmol command scripting language. You save the "state script" from Jmol in Proteopedia. Instructions are provided both for making the script file, and for using it in a web page in Proteopedia.
+** An '''example''' of a web page created by this method is [[Molecular Playground/Relenza]].
+** '''Instructions for creating your custom scene and saving the state script are in [[Molecular_Playground/Procedures]].'''
+**''' Instructions for creating your web page are below, under [[#Web Page Procedure in Proteopedia]].'''
-===A Single Molecular Scene, Spinning===
+* '''For Advanced Jmol Users:''' By hand. This requires familiarity with the [http://chemapps.stolaf.edu/jmol/docs/ Jmol Command Scripting Language]. No instructions are provided here for this method, either for constructing the script file, or for making a supporting web page. See [[#Technical (All Three Levels)]] below for how your script will operate on MP.
-The '''simplest option''' is a '''single customized molecular scene''',  with the molecule '''spinning''' slowly. Such a scene, lacking complicated animations, can be created in Proteopedia -- without learning any Jmol scripting language. Proteopedia offers ''Molecular Scene-Authoring Tools'' that make this relatively easy. Details will be found below under [[#Procedure|Procedure]], but first, let's look at a concrete example.
+===Level II: A Single Molecular Scene With A Color Key===
+This method is a bit more complicated than Level I. The only advantages are that adding a color key is easy, and have a "zooming in entrance" is easy. Let's look at a concrete example.
 <applet size='[450,338]' frame='true' align='right' scene='User:Eric_Martz/Molecular_Playground/Authoring/3ckz_relenza_tyr274/9' caption='Relenza binding to influenza neuraminidase N1 mutant H274Y (3ckz).' />
@@ Line 88: / Line 90: @@
 <text>Add Banner</text>
 </jmolButton>
-</jmol>
+</jmol>*
 ([[:Image:MP_relenza01.spt|MP_relenza01.spt]])
+<br>
+* This is also how a Level I module would look.
 Next, we'll use the MP support script (explained below) to add a color key<ref name="button" />.
@@ Line 113: / Line 117: @@
 </jmol>
 ([[:Image:MP_relenza03.spt|MP_relenza03.spt]])
+A module at Level II consists of:
+# A master (top level) Jmol script file.
+# A Jmol state script file that produces the customized molecular scene.
+# A [[PDB file]] that provides the molecular model displayed by the scripts.
+# The URL of your "more information" web page. If your web page is not yet ready, this can be submitted later.
+In a Level II module, the banner text is built into the master script file. The script files use support scripts that are already available in MP, and are common to all modules.
 ====Procedure====
-The step-by-step procedure for constructing scripts, similar to those exemplified above, will be found at [[Molecular Playground/Procedures#Installing a state script from Proteopedia]]. This procedure includes an explanation of how to use the MP Support scripts that will be required ([[Image:MPSceneVersion01.spt]] and [[Image:MPSupportVersion01.spt]]).
+The step-by-step procedure for constructing Level II scripts, similar to those exemplified above, will be found at [[Molecular Playground/Procedures]]. These procedures explain how to use the MP Support scripts that will be required ([[Image:MPSceneVersion01.spt]] and [[Image:MPSupportVersion01.spt]]).
+After preparing the script files, you can finish your web page, following the instructions below: [[#Web Page Procedure in Proteopedia]].
-===A Complex Animation===
+===Level III: A Complex Animation===
-If your module will be more complex than can be produced by a single scene in Proteopedia, then you will need to write much of the script by hand. However, we still strongly recommend that you first do a module based upon a single Proteopedia scene. This will familiarize you with key points that will not be repeated below.
+If your module will be more complex than can be produced by a single scene in Proteopedia, then you will need to write much of the script by hand. However, we still strongly recommend that you first do a Level II module. This will familiarize you with key points that will not be repeated below.
 In creating a script for a complex animation, you don't have to start from scratch! You should start by downloading the script from whichever of these existing modules has the most in common with your plans:
@@ Line 134: / Line 148: @@
 * growSpacefill() and growWireframe() make the selected atoms "grow" slowly into spacefilled or wireframe representations, permitting rotation by the onlooker during these transitions.
 If you need a transition or function that is not included, don't hesitate to ask for help in adding it. Please contact {{Template:Martz_email}}.
+===Technical (All Three Levels)===
+MP takes responsibility for loading the PDB file before your script is run, and it adds a delay after your script is run so that your scene will spin for a while before a repeat cycle of your script, or a different script, is run. For all three levels, MP defines the following variables before any master script is run:
+* PlaygroundProjection = true; # this if false if undefined
+* PlaygroundContentPath # the path on the MP server to your .spt and .pdb files. The filename must be appended to this.
+* PlaygroundSupportScriptPath # the path on the MP server to MPSupportVersion01.spt and MPSceneVersion01.spt. The filename must be appended.
+<!-- Adam plans in April 2011 that these will become:
+PlaygroundModelPath
+PlaygroundScriptPath
+PlaygroundSupportPath
+-->
 ==Web Pages==
@@ Line 154: / Line 181: @@
 Your MP web page need not be in Proteopedia. You can put it on another server if you prefer. If you use a server other than Proteopedia, the procedures here do not apply, and you will need to know how to build HTML pages and how to use Jmol.
-===Procedure for using Proteopedia===
+===Web Page Procedure in Proteopedia===
 <ol>
 <li>
-'''Identify the page''' in Proteopedia where you will develop your article to provide more information as a supplement to your module in MP.
+'''Identify the page''' in Proteopedia where you will develop your article to provide more information as a supplement to your module in MP. Most likely you already set up this page and developed your scene there (see [[Molecular_Playground/Procedures#Create_a_Customized_Molecular_Scene_in_Proteopedia]]).
-There are three options:
+We recommend that you develop your web page in a temporary, protected page that you create named '''User:Your Name/Sandbox 1''' (or 2 or higher if you already have a Sandbox 1). For instructions on how to create this page, see [[Help:Sandboxes#Protected_Sandbox_Pages]]. After you have completed the development of the content in your page, you can move the content to a new permanent page named '''Molecular Playground/Your Molecule''' (see the last item below).
-<ol type="a"><!-- sublist -->
-<li><!-- sublist -->
-A '''protected''' page that only you can edit. This can be the temporary or permanent location of your web page. See [[Help:Protected Pages]].
-</li><li><!-- sublist -->
-A '''page that only you can view'''. If you are uncomfortable about others seeing your page while you are developing it, you could use this option. Note that Proteopedia administrators can see such pages. For instructions, see [[Proteopedia:Workbench]].
-</li><li><!-- sublist -->
-A '''permanent page'''. Such a page should be titled "Molecular Playground/Your Molecule" (where "Your Molecule" is replaced by the name of your molecule). This will distinguish it from a page titled simply "Your Molecule", which would be intended to treat the subject in more depth for an audience of scientists. Content developed on a protected page or a workbench page could be moved to such a permanent page when it is finished. For instructions, see [[Help:Editing#How_To_Create_A_New_Page]].
-</li><!-- sublist -->
-</ol><!-- sublist -->
 </li><li>
-Write the text for your page, dividing it into logical sections. See the example pages linked [[#Web Pages|above]]. On the [[#Web Pages|example pages]], use the ''edit this page'' tab to see how the wikitext is done, then Cancel editing (so that you don't change the example pages).
+When you were developing your molecular scene, you installed a rectangular Jmol into your page. Now, you can specify that your custom scene will be automatically displayed when the page loads, rather than having to press a green link. To do this, insert the <font color="red">red</font> line below into your &lt;applet ... /&gt; tag.
+:&lt;applet size='[450,338]' frame='true' align='right'
+:<font color="red">scene='XXX'</font>
+:caption='YYY' /&gt;
 </li><li>
-Copy the applet tag below and paste it into your page where you want Jmol to appear. This makes a rectangular Jmol with the correct shape for MP.
+Replace 'XXX' with the name of your scene: Copy the name of the scene from the green link &lt;scene name='...'> tag that shows your scene. Copy the quoted name (without "name=" and without the quotes), and paste that to replace XXX. Make sure the scene name has one single quote mark at each end. Save your page. Your scene should appear automatically a moment after the page loads. After you are satisfied that the scene is loading correctly, you can delete the green link(s) you used to develop the scene, unless you want to keep more than one scene to accompany the explanation in your page.
-<pre>
-<applet size='[450,338]' frame='true' align='right'
-scene='XXX'
-caption='YYY' />
-</pre>
-Make sure there are no spaces before any of the lines you pasted in.
 </li><li>
-Replace 'XXX' with the name of your scene: Edit the page where you developed the scene, and show the ''Scene Authoring Tool''. Load the scene. In the ''Wikitext'' box (at the bottom) copy the quoted name (without "name="), and paste that to replace XXX. Save your page. Your scene should appear automatically shortly after the page loads. This "state script" version of the scene lacks the banner, color keys, etc. that your module displays in MP.
+Replace 'YYY' with a descriptive caption for your scene. This is a good place to mention the [[PDB code]] for the model you are showing. Put the lower case PDB code between double square brackets, like this <nowiki>[[3ckz]]</nowiki>, which will make a link like this: [[3ckz]].
+</li><li>This step applies '''only to Level II''' modules, and even for those, it is '''optional''': Insert a button that will show the scene as projected in MP. See [[Molecular Playground/Procedures#Displaying a Level II Scene in a Proteopedia Web Page]].
 </li><li>
-Replace 'YYY' with a descriptive caption for your scene. This is a good place to mention the [[PDB code]] for the model you are showing. Put the lower case PDB code between double square brackets, like this <nowiki>[[3ckz]]</nowiki>, which will make a link like this: [[3ckz]].
+Write the text for your page, dividing it into logical sections. See the example pages linked [[#Web Pages|above]]. On the [[#Web Pages|example pages]], use the ''edit this page'' tab to see how the wikitext is done, then Cancel editing (so that you don't change the example pages).
-</li><li>'''Optional:''' Insert a button that will show the scene as projected in MP: see [[Molecular Playground/Procedures#Displaying_your_script_in_a_Proteopedia_web_page]].
 </li><li>
 Insert <nowiki>{{Template:MP_masthead}}</nowiki> at the top of your page to show the MP masthead photographs. Depending on what follows, you may need to put several blank lines after it to force the ''Contents'' table down, as done in [[Molecular_Playground/HIV_Protease_Inhibitor]]. Or you may need to insert <nowiki>{{Clear}}</nowiki> as done in [[Molecular Playground/Tamiflu]].
+</li><li>
+At the very bottom of your page, paste in <nowiki>[[Category: Molecular Playground]]</nowiki>. This adds your page to that Category, which lists all such pages.
+</li><li>
+Just above the previous item, paste in <nowiki>{{Template:Molecular Playground animation description}}</nowiki>.
 </li><li>
 Search for related pages in Proteopedia, Wikipedia, and the scientific literature and provide links to them.
-</li><li>
-Near the bottom of your page, include <nowiki>{{Template:Molecular Playground animation description}}</nowiki>.
 </li><li>'''Optional:''' Near the bottom of your page, include a ''Methods'' section, patterned after those on the [[#Web Pages|example pages]], with links to all the scripts and PDB files employed on your page.
 </li><li>
-At the very bottom of your page, add <nowiki>[[Category: Molecular Playground]]</nowiki>. This adds your page to that Category, which lists all such pages.
+Create a new, permanent page in Proteopedia named ''Molecular Playground/Your Molecule'' (substituting the name of your molecule for ''Your Molecule''). See [[Help:Editing#How To Create A New Page|How To Create A New Page]]. Move the contents of your ''Sandbox 1'' page to a permanent page title: see [[Help:Sandboxes#Publishing Your Completed Article]].
 </li><li>
-Notify the MP team (see email addresses at [http://molecularplayground.org MolecularPlayground.Org]) asking them to link your page.
+Email the address (URL) of your permanent web page to the MP team (see email addresses at [http://molecularplayground.org MolecularPlayground.Org]) asking them to add a link to your page.
 </li>
 </ol>
@@ Line 199: / Line 216: @@
 ==Notes and References==
 <references />
+==See Also==
+* [[Molecular Playground]]
+* [[CBI Molecules]]
 [[Category: Molecular Playground]]