{{:wizard:wizard48.png?50|}}

====== Wizards ======

:!: The wizard editor is available in Dinamica EGO since version 1.8. However, this tutorial refers to the version currently available in Dinamica EGO 2.0 and later. See Youtube videos below for current layout and procedures.

===== What is =====

A Wizard is an easy way to create a presentation for a model developed in Dinamica EGO with formatted 
text, images and other graphical features. In a Wizard it is also possible alter the models'inputs to run an easy simulation without an advanced understanding of the Dinamica GUI and its functors. A Wizard Tutorial is a 
sequence of pages containing formatted text, tables, images, diagrams, animations, embedded 
videos or any other internet browser compatible technology inserted by the author. Each page can contain general information 
about the model and the simulation inputs. Simulation inputs can be directly linked to script inputs, making
it a fast and easy way to set parameters and run a simulation.

[{{ :wizard:wizard_presentation.png?nolink&900 |Wizard overview}}]
[{{ :wizard:wizard_model_correspondence.png?nolink&800 |Model-wizard correspondence}}]

A model author creates their own Wizard Tutorial to present and explain its concepts and ideas. The Wizard Editor is a powerful tool to create text, format information and illustrations visually, include tables, and set inputs/outputs. The author selects model script functors to include in the Wizard so not all functors are visible to Wizard users. 

{{ :wizard:editor1.png?nolink&700 |Wizard editor in use}}

So, if you are a model author, it is a good idea to create a wizard to make it easier for other users to understand
and run your model.

<note tip>
A Wizard example can be found within the Dinamica EGO examples files. They are usually installed in
the directory:

C:\Documents and Settings\User Name\My Documents\Dinamica EGO\Dataset\Examples\run_lucc_northern_mato_grosso\run_roads_wizard
</note>

===== The Tool =====

It is important to present a extant hierarchy in a tutorial that guides the user through the model. The Wizard
should be a logical sequence of pages, each using a graphical area to convey information and possibly ports linked to the model. This is a very clear idea that can be seen in the wizard editor. The following videos provide directions on using the wizard tool:

{{youtube>_Jc61ARsHuA?medium}}

Here is how to run a Wizard in the current interface:
{{youtube>I7DPear5yao?medium}}

To open Wizart tool click on the edit bar in the menu:

{{:wizard:editor_menu.png?nolink&|Editor button in menu}}

It has an intuitive interface that we are going to learn how to use through the examples.

{{:wizard:editor_interface.png?nolink&|Wizard editor intuitive interface}}

===== Examples =====

==== Simple Wizard ====

Lets start with a quick example where we create a wizard for a script that performs only a simple map
algebra operation.

We are going to need the functors:
  * [[Load Map]]
  * [[Calculate Map]]
  * [[Number Map]]
  * [[Save Map]]

=== Building the model ===

How we build the model:

{{:wizard:model.png?nolink&|Simple model}}

In the [[Calculate Map]] we are going to perform a simple operation with the input that is filter the
values equals to **null**, set them to **1** and set **0** to the others.

{{:wizard:expression.png?nolink&|Expression used to filter the input map null values}}

=== Creating the Wizard ===

To create a wizard o need first to save your model. Save it with XML extension and open the wizard
editor. 

== Wizard Pages ==

In the Dinamica Wizard Editor toolbar click in the wizard icon to input ports.

{{:wizard:create_page.png?nolink&|Create new wizard page icon}}

It is necessary to give a page a name, but it is only for identification. The tutorial user will not
see this name:

{{:wizard:page_name.png?nolink&|Wizard page valid name}}

Now lets edit this page and add some text. To edit a page can just click on edit wizard at the 
icon wizard:

{{:wizard:edit_wizard.png|}}

The page editor will be showed up:

{{:wizard:page_editor1.png?nolink&600|Page Editor}}

Indeed, it is a visual text editor, "what you see is what you get" style. Lets add some text about
our model.

{{:wizard:page_text1.png?nolink&|Page text example}}

== Formatting ==

We can use the editor features to add some formatting:

{{:wizard:page_text_formatted.png?nolink&|Page text example formatted}}

By clicking ok the page will be visualized in the Wizard Editor:

{{:wizard:editor2.png?900|}}

== Another Page ==

Now lets add another page. You already know how to proceed.

{{:wizard:create_page2.png?nolink&|Second page created}}

In this second page we are going to allow the user to set the input map file path for the filtering.
For now, lets add a text about it and soon we will add the input in the wizard.

{{:wizard:editor3.png?900|}} {{:wizard:wizr_editor.png?900|}}


== Adding Inputs ==

Now, lets add one input to our wizard. To do this, double click the second page to edit it. In the 
page inputs area, click in the **Add input** button to add a new input.

{{:wizard:add_input.png?nolink&|Add input button}}

The **Select functor port** window will open up. In this window, the [[Load Map]] functor present in our model can be
seen. Select page 00 and press ok.

{{:wizard:functor_selector.png?nolink&|Functor selector window where we select functors whose inputs will be exported to the wizard}}

<note tip>Tip: Assign meaningful alias to each of the functors. It is easier to identify them while selecting functors and ports.</note>

Now, you can edit the port title and description. This is an important feature because ports for a functor
have all the same title and description. With the wizard you can specify this information with an intuitive
text, something that explain better what is this input for your simulation.

{{:wizard:input_description.png?nolink&|Input title and description editor}}

Lets add a new title and description that explains better this input:

{{:wizard:input_description_edited.png?nolink&|Input title and description edited}}

After clicking ok the input will appear in the page inputs area:

{{:wizard:page_inputs_new.png?nolink&|Input added to the page}}

If you select an input from this area the buttons will be available. Through this you can remove the selected
input, edit its information again (modify title and description) or change the inputs order (move it up or down)
when there are more than one input.

{{:wizard:page_input_buttons.png?nolink&|Page input buttons}}


== Testing the Wizard == 

To test the wizard you have made you can click the button **Run Wizard** in the tool bar:

{{:wizard:test_wizard_button.png?nolink&|Test wizard button}}

After clicking Run Wizard you must select the model that will contain the wizard and run the model.

{{:wizard:run_model.png|}}

Clicking **Cancel** you can keep editing the Wizard.

<note important>Remember to save the wizard every time you close the Wizard Editor. Once finished the Wizard it
is also important to save your model.</note>

== A third page ==

Now you know the process to create a page and add an input. Lets do it faster. In the third page we are going
to add some information about the output map and after export the [[Save Map]] **Filename** port we are going
to add it as an input to the third page.

We create the page and add information.

{{:wizard:third_page_edit.png?nolink&|Editing third page text}}
{{:wizard:third_page_created.png?nolink&|Third page created}}

Now add an input, choose the [[Save Map]] functor (you need to click in the wizard tool on the save map) and then his input port named "Filename".

{{:wizard:save.png|}} {{:wizard:next_step.png|}}

After that you have to click in Edit Wizard.

{{:wizard:edit_wizard.png|}}

Choose a name for the input and set a meaningful title and description.

{{:wizard:output_description.png?nolink&|New description to Save Map Filename port}}
{{:wizard:third_page_inputs.png?nolink&|Third page inputs}}

== Finishing the Simple Wizard ==

You have just created a complete wizard tutorial for your model! Save the wizard and close the editor. It is also 
important to save your model again.

Now, every time an user opens your model, he will be prompted about running the wizard tutorial you have created.

{{:wizard:run_wizard_prompt.png?nolink&|Prompt for running a wizard}}

It is also possible to run the wizard tutorial through the **Run Wizard** button in the tool bar.

{{:wizard:run_wizard_button_toolbar.png?nolink&|Run wizard button in tool bar}}

==== Conway's Game of Life Wizard ====

The [[wp>Conway's Game of Life]] is a cellular automaton zero-player game where a initial state is
defined and interactions between the cells results in a new state for each game iteration. Some simple
rules are used to decide if a cell will born, stay alive or die. This automaton was a base for many
studies in [[wp>Artificial Life]].

A Dinamica EGO implementation for this game is available in the installation directories:

C:\Documents and Settings\User Name\My Documents\Dinamica EGO\Dataset\Examples\game_of_life

To create a Wizard Tutorial for this model, stay tuned with the concepts discussed in this tutorial 
until now. We are going to be faster now.

==== Open the model ====

Open the model

C:\Documents and Settings\User Name\My Documents\Dinamica EGO\Dataset\Examples\game_of_life\Run\game_of_life.xml

in the Dinamica EGO interface. Take a look at the functors, the comments inside it and understand what
each one is doing there.

{{:wizard:gof_model.png?nolink&|Game of life Dinamica EGO model}}

== The Wizard ==

Open the wizard editor and create a page. Take a look at the Wikipedia's page for the 
[[wp>Conway's Game of Life]] copy some information from there and paste it in the page.

{{:wizard:gof_page1.png?nolink&|Game of Life wizard first page}}

Now, import the wizard in a file within the model. In the directory **game_of_life**, create a directory called 
**wizard** and save the file **wizard_gof.egow**. 

{{:wizard:gof.png|}} 

<note tip>Always save the wizard after some modification and before closing the Wizard Editor. </note>

== Using Images ==

Lets add an image in this firts page to illustrate the game in action. Wikipedia offers a good example in the
following URL:

http://upload.wikimedia.org/wikipedia/commons/e/e5/Gospers_glider_gun.gif

Lets download that image to use it in our wizard. I usually right click the image and select the //Save image as...//
option. It is very important to save the images used in a subdirectory whithin the wizard file. This way 
portability is easier. Create a folder called **images** inside the **wizard** folder and put your images there.

{{:wizard:images_folder.png?nolink&|Folder for images}}


<note warning>Save the images used in your wizard in a folder whithin the wizard file to facilitate portability.</note>

== Inserting Images ==

It is easy to add an image to a wizard page. In the Page Editor you can find an icon for it:

{{:wizard:insert_image_icon.png?nolink&|Insert image icon}}

An interface to set the image properties will open up. If you have some trouble to fully visualize it you can resize
the Page Editor window.

{{:wizard:image_properties.png?nolink&|Image properties window}}

As you can see, there are two tabs of properties: **General**  and **Apperance**. In the **General**
tab there is a field for the image **URL**. You should insert there the //absolute// path to the image file in you
computer. In this example the absolute path is:

C:\Documents and Settings\Administrador\Meus documentos\Dinamica EGO\Dataset\Examples\game_of_life\wizard\images\Gospers_glider_gun.gif

This is why it is important to keep the images in a file within the wizard file. Dinamica Wizard automatically find the 
image even if you change computers since you keep that directory structure.


You can change the image size in the **Width** and **Height** fields or set a tooltip in the **Alternative Text**
field. In the **Link** tab you can set an URL to redirect the user when he clicks the image.

In then Page Editor we have centralized the image.

{{:wizard:image_added.png?nolink&|Image added}}

== A Second Page ==

Now that we have a very good first page, lets create a second one to explain the game rules. I will user the information
in http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life#Rules to create a table that relates number of neighbours and
cell state.

== Tables ==

You can create a table through the table icon in the Page Editor:

{{:wizard:table_icon.png?nolink&|Table icon}}

You can choose rows and columns of your design table.


{{:wizard:table_properties.png?nolink&|Table properties window}}

These fields are very intuitive. We are going to create a table with 5 rows and 3 columns to write down the game rules.

{{:wizard:table_blank.png?nolink&|A blank 5x3 table}}

I have divided the rules in number of neighbours, cell state and reason. After creating a table you can write and format
the text on it.

{{:wizard:gof_page2.png?nolink&|Second page}}

== A Little Modification == 

Remember to save you wizard often. Close the Wizard Editor after save and lets make a little modification in the model.
In the first [[Calculate Map]] that //generates the initial 'seed'//, add a [[Number Value]] and link a [[Real value]] to
its **Value** port and set the **Value Number** to **1**. Edit the Real value alias, using the "Comment Editor" editor, and
change it to "Percentage of living cells".

{{:wizard:model_mod.png?900|}}

Edit this **Calculate Map** expression to set a cell as alive based on the **v1** value and not by **0.3**.

{{:wizard:exp.png?nolink&|New expression}}

Now we can control the percentage of living cells in the initial state through the value in the [[Real value]] functor.

== The Wizard Inputs ==

In the Wizard Editor, create a third page to receive the inputs and add the Real value.

{{:wizard:page3.png?nolink&700|Third page}}

Set an intuitive title and description.

{{:wizard:input_percent.png?nolink&|Percent title and description}}

Now the user will be able to set this parameter through the wizard.

{{:wizard:page3_view1.png?nolink&|Third page visualization}}

Try to add more inputs.

== Finishing ==

Run the wizard and the model.

{{:wizard:test_page3.png?nolink&700|Testing the wizard}} {{:wizard:run_page3.png?700|}}

You have finished the wizard construction for the Conway's Game of Life model! You learned some new features and
are ready to create your own wizard tutorials for your models.

===== Other Features =====

==== Youtube videos ====

It is easy to embed Youtube videos in your wizard. Go to [[http://www.youtube.com|Youtube's]] page and choose a video.
I have choosed this one:

https://youtu.be/uUtQZ41LSLk

Click on the **Share** button.

{{:wizard:share1.png?nolink&|Youtube video share button}}

Click on the embed button: {{:wizard:embed_button.png?nolink&|Embed}}

Select and copy the code in the text box.

{{:wizard:code_selection.png?nolink&|Selected code}}

Edit the page you want to put the video and click the ** HTML Source** button.

{{:wizard:source_button.png?700|}}

Paste the code you have copied in the body of the text.

{{:wizard:code_pasted.png?nolink&|Code pasted}}

Clicking ok and testing the wizard you can see the video there.

{{:wizard:test_video.png?nolink&700|Test video}}

<note important>Internet connection is required to watch youtube videos in a wizard.</note>