1. Documentation
2. 10.1 (Latest)10.09.109.99.89.79.69.59.49.39.29.19.08.28.18.07.6
3. Developers
4. Extensions
5. Create custom tutorials

Create custom tutorials for your extension

This article will guide you through:

• Designing a new tutorial
• Bundling the tutorial with your extension

Designing a tutorial

Tutorials are self-contained files that can be distributed via extensions or loaded from your local file system. While the file format is simple, it is important to comply with the structure described below.

File format

Tutorials are ZIP archives that use the.tutorialfile extension and contain at least one file and a folder with three files:

my_tutorial.tutorial ├── groups.properties └── tutorial1 ├── process.rmp ├── tutorial.properties └── steps.xml

Thegroup.propertiesfile defines the name of the chapter of tutorials and contains a short description. It must be encoded asISO-8859-1– in particular, unicode encodings will most likely not work. Based on the example above, the file's content could look like this:

template.name=My first tutorial chapter template.description=This is my first tutorial chapter.

The tutorial zip contains a folder for every tutorial; in the example above there is only one folder with the nametutorial1.

Thetutorial.propertiesfile defines the name of the tutorial and contains a short description - again encoded asISO-8859-1. For the example above, the file's contents could be like so:

template.name=My first tutorial template.description=This is my first tutorial.

The tutorial folder must contain exactly one RapidMiner process (*.rmp).

Furthermore, it must contain asteps.xmlfile that describes the steps of the tutorial. The format of this file is explained in the next section.

In addition to these files, you can bundle arbitrary repository entries. For instance, you can include a certain data set into your template by copying the corresponding files from your local repository. More so, you can use an image as a background to your toturial process, by adding the image file after changing its extension to.blob. An example for this can be found below.

Format of the steps.xml

Thesteps.xmlfile determines what is displayed in the tutorial panel that opens on the left side of RapidMiner Studio when a tutorial is in progress. Its content must be build following these rules:

• The content of thesteps.xmlfile must be wrapped into a steps tag

    ... 

• The actual tutorial is broken down into an arbitrary number of steps, each step is wrapped into a step tag and can have the attribute name:

  ...

  You can use arbitrary content in each step. This will just be shown as is. Don’t use any special HTML or styling since the tutorials will be compiled into other formats. Also avoid special characters for HTML or XML like the greater-than-symbol.

• There is a special content type for tasks which work similar to ordered lists in HTML:

   ... ... 

• Another important element besides tasks is the info section which can be used to give more background information or describe other important facts or concepts. You can use arbitrary content within an info section including all tags described below. You cannot define tasks or steps within an info section though. The format is:

  ...

• At the of each tutorial is a section of questions where learners are encourage to try out different things or can check what they learned in this tutorial. Those questions work in general exactly like the tasks block:

   ... ... 

• For a normal text block that is neither task, nor info or question use a text tag:

  > <文本。..

• In content, tasks, or info sections, you can add hyperlinks with the link tag:

  name

• You can emphasize content with the emph-tag:

  ...

• You can add UI icons to the text with the icon tag. Here you can either use the full resource path to an icon

  path/to/icon.png

  or use icons delived with studio by using the format icon size/icon name, e.g.,

  /16/media_play.png

• The following tags should be used in all types of content to mark the corresponding types:

  • Operator Name

  • Parameter Name

  • Parameter Value

  • Repository or Folder Name

  • <文件>文件或存储库条目名称> < /文件

  • Name of UI element

  Any hierarchy (operators, folders, ..) can be specified by using a '/'

• To open the next tutorial add the following at the end of a tutorial:

  START NEXT TUTORIAL

The following section covers an example for asteps.xmlfile.

Developing tutorials

You can load your tutorial processes locally without bundling them with your extension. Bundling becomes only necessary if you want to dirstribute your tutorials.

All you need to do is to move the tutorial archive into your.RapidMiner\tutorialsdirectory. Please note that tutorials stored in that directory supersede bundled tutorials: if you bundle a tutorial with your extension and have a local copy of the tutorial installed, only the local copy will be loaded.

A minimal tutorial

Let us start with a simple tutorial group with only one tutorial containing a single step.

To create the process file open a new process in RapidMiner Studio and drag aGenerate Dataoperator onto the process canvas:

Export the process via theFilemenu (choseExport Process…) and save it astutorial1.rmp. Note that you can also leave the process empty and export it the same way if you want your tutorial to start with an empty process.

Next we need asteps.xmlfile that describes what to do with this process:

    Have fun with the tasks below!    Connect  the "out" port of Generate Data with the result port on the right.   16/media_play.png Run the process.     What happens if you run the process without the connection?    

As last file for the tutorial folder, we need to create thetutorial.properties文件:

tutorial.name=First tutorial tutorial.description=A minimal tutorial.

We put these three files together in a folder that we call just1.

The last file we need is thegroup.properties文件描述整个教程组(制作h contains only one tutorial in our simple case):

group.name=First tutorial chapter group.description=A minimal tutorial chapter.

Finally, we need to create the tutorial archive. For this purpose, create a new ZIP archive containing thegroup.propertiesfile and the folder1using an archiver of your choice. Then change the file extension from*.zipto*.tutorial, e.g., renamesample.ziptosample.tutorial. The final file structure should look as follows:

sample.tutorial ├── groups.properties └── 1 ├── tutorial1.rmp ├── tutorial.properties └── steps.xml

Make sure that your tutorial file does not contain an extra folder betweensample.tutorialand thegroup.propertiesfile and the folder1.

To load the newly created tutorial chapter, copy the tutorial file to.RapidMiner/tutorialsand restart RapidMiner Studio. In theLearnmenu, you should now see the newly created template:

Selecting the first (and only) tutorial of the new chapter should open up the process we created in the first step and show the step on left hand side.

Including repository entries

Let us now add a custom data set to use in the tutorial. To do this, we first need this data to be in therepositoryof RapidMiner Studio.

For example, we can get some custom data into our repository as follows: As before, drag theGenerate Dataoperator onto the process panel. Now add aStoreoperator and connections.

Configure theStoreoperator to store the data set in your repository, e.g., as//Local Repository/Custom data, and run the process.

Now, alternative-click on the newly created entry in the repository and chooseOpen in file browser. There are three files with the name "Custom data":Custom data.ioo,Custom data.mdandCustom data.properties. Copy the.ioo(the actual data) and the.md(meta data) file and add them to the tutorial archive such that it has the following new structure:

sample.tutorial ├── groups.properties └── 1 ├── tutorial1.rmp ├── tutorial.properties ├── steps.xml ├── Custom data.ioo └── Custom data.md

Restart studio and have a look at theSamples存储库:

You can see that theCustom datais now part of the tutorial folder1. We can now add a second step to thesteps.xmlusing the new data:

    Have fun with the tasks below!    Connect  the "out" port of Generate Data with the result port on the right.   16/media_play.png Run the process.     What happens if you run the process without the connection?        Drag  the data from the Repository at //Samples/Tutorials/samples/1/Custom data into the process.    Connect  the "out" port of Retrieve with the second result port on the right.   16/media_play.png Run the process.     What is the difference between the two resulting data sets?    

The result (after restarting RapidMiner Studio) looks as follows:

You can also use theCustom datain your process filetutorial1.rmpvia aRetrieveoperator, but you must use the absolute path//Samples/Tutorials/samples/1/Custom data.

Adding a background image

You can use a background image to give hints how to fill the process canvas, for example:

The easiest way to construct such an image is to take a screenshot of the finished tutorial process and adapt it with the graphics program of your choice.

We change the file extension to.blob, e.g., rename thebackground.pngfile tobackground.bloband add the.blobfile into the folder1:

sample.tutorial ├── groups.properties └── 1 ├── tutorial1.rmp ├── tutorial.properties ├── steps.xml ├── Custom data.ioo ├── Custom data.md └── background.blob

Furthermore, we tell our processtutorial1.rmpto include the background image by adding the line

at the inner process, i.e., the last lines should look like this:

You can adjust the position of the background image by adjusting the x and y values. The easiest way to try different values is to use theXML panelin RapidMiner Studio and then to adjust thetutorial1.rmpfile with the optimal values.

The tutorial process now looks like this:

Now you can add a second tutorial, for example

sample.tutorial ├── groups.properties └── 1 │ ├── tutorial1.rmp │ ├── tutorial.properties │ ├── steps.xml │ ├── Custom data.ioo │ ├── Custom data.md │ └── background.blob └── 2 ├── tutorial2.rmp ├── tutorial.properties ├── steps.xml …

Don't forget to add

START NEXT TUTORIAL

at the end of the last step of your first tutorial.

Bundling tutorials

Bundling tutorials with your extension is a straight forward process. All you have to do is to add your tutorial archives as resources and register them in the initialization code of your extension.

If you have no experience with writing extensions yet, please refer to our guideCreate your own extension. Sections 1-3 cover all you need to know to build an extension that can be used to distribute templates.

Adding tutorials as resources

By convention build tools such as Maven and Gradle look for resources in thesrc/main/resourcesdirectory. We recommend using this structure for RapidMiner extensions as well.

Let us assume that you choseorg.myorg.myextension组id。那么你的资源urces should be located undersrc/main/resources/org/myorg/myextension. Note that RapidMiner will add thetutorialdirectory to the path automatically. Thus, you could bundle the tutorial created above as…/org/myorg/myextension/tutorial/sample.tutorial:

my_extension ├── README.md ├── build.gradle ├── … ├── src │ └── main │ ├── java │ │ └── … │ └── resources │ ├── org │ │ └── myorg │ │ └── myextension │ │ └── tutorial │ │ └── sample.tutorial │ └── … └── …

However, RapidMiner will not search for resources in that directory unless you register the location as resource source. This can be easily done in the initialization code of your extension. All you need to do is to add the following line to theinitPlugin()method:

/ * * *后直接调用这个方法将the extension is initialized. This is the first * hook during start up. No initialization of the operators or renderers has taken place when * this is called. */ public static void initPlugin() { // register extension resources Tools.addResourceSource(new ResourceSource(PluginInitMyExtension.class.getClassLoader(), "org/myorg/myextension/")); }

Now you can register extension via the so-called tutorial registry. To register the tutorial designed above, you could add another line to the plugin initialization code:

public static void initPlugin() { // register extension resources Tools.addResourceSource(new ResourceSource(PluginInitMyExtension.class.getClassLoader(), "org/myorg/myextension/")); // register sample tutorial TutorialRegistry.INSTANCE.register("sample"); }

Testing the tutorials

There are no further special steps involved in testing the bundled tutorials. All you need to do is to build a new version of your extension, e.g., via the commandgradle clean installExtension.

But keep in mind that tutorials stored in your.RapidMinerdirectory override bundled tutorials of the same name. Thus, make sure to remove all working copies of your tutorials before starting RapidMiner Studio.