It is supposed that you are familiar with the basic terms of XProc and xml, such as pipeline, input and output ports, options, parameters and so on.
- How to start?
- Using the visual input form
- The "INPUTS" section
- The "OPTIONS" section
- The "OUTPUTS" section
- One more thing: Information about the pipeline
- Running a pipeline
- Inspecting and saving the results
- Saving settings in the visual input form
- The "Pref"-button and the Preference menu item
Since version 0.95-3 MorganaXProc comes with a graphical user interface in addition to the command line interface already provided with prior versions. The new graphical user interface (GUI) makes it even easier and more intuitive to provide an XProc pipeline with input documents and options, run the pipeline and then inspect and/or save produced results. Here is a typical workflow using the new GUI:
- Choose a pipeline somewhere in your filesystem and provide it to MorganaXProc by just dragging and dropping the file's icon to MorganaXProc's greeting screen.
- MorganaXProc will now analyze the XProc pipeline, identify all the declared input and output ports as well as the declared options and create a visual form for you.
- You then fill in the form again just by dragging and dropping the xml documents you want to appear on the input ports of the pipeline to the corresponding input field in the visual form. Of course the form will also provide input fields, where you can set values for the pipeline's option. Additionally you can choose where MorganaXProc should save the pipeline's results permanently on your filesystem.
- Your then hit "Run" and MorganaXProc will compile and run XProc pipeline with your selections, providing you with some information about the pipeline's run.
- After a successful run, the result browser will open up and provide you with a graphical view of your results. You can inspect all the documents produced by the pipeline run and you can save all or some of them again just by dragging and dropping icons representing the documents to your filesystem.
Interested? Let us see in detail, how to work with MorganaXProc's GUI. If you are more into the traditional way of running pipelines from the command line interface, you will find the documentation here.
When you start MorganaXProc by double clicking on MorganaXProc.jar, you will first see the following greeting screen:
To run a pipeline with MorganaXProc's GUI just drop the icon of a file containing an XProc pipeline to the center of the greeting screen. For MorganaXProc to recognize the pipeline, the file can have any name and extension, but it must be a valid xml document and it must contain an XProc pipeline. (Technically: The root element of the document in the file must be in XProc's namespace.)
As an alternative you can also type in the uri of the pipeline document. This is handy if you want the run a pipeline from a source on the internet, which you can not drop. To do this, just double click on the greeting screen. The following dialog will pop up:
Just type in the uri of the pipeline you would like to run and hit "OK". For example you might type in "https://www.xml-project.com/files/pipelines/gui‑welcome.xpl" to load a pipeline from our home page. Of course you can also copy and paste the uri using the familiar key of your operation system ("CMD-C" on MacOS and "CTRl-C" on Windows).
But for now: Let us use the drag and drop feature to provide MorganaXProc with a pipeline. You will find a pipeline in a file called "gui‑welcome.xpl" in the "pipelines" folder next to "MorganaXProc.jar". Take the icon and drop it on MorganaXProc's greeting screen. As you see, the screen will change its color if your icon is over the drop zone. Release the mouse key and your done: MorganaXProc knows, which pipeline you want to run.
MorganaXProc will now identify all the input and output ports declared in the selected pipeline as well as the declared options and provide you with a visual input form for this pipeline. For 'gui‑welcome.xpl' the form will look like this:
As you see, the form is divided into three parts, called "INPUTS", "OPTIONS" and "OUTPUTS" representing the declared input ports, the declared options and the declared output ports of the chosen pipeline respectively. Our pipeline has one input port called "source", one option called "user" and two output ports called "result" and "infoport".
Next we will discuss, how to bind the pipeline's input ports, set values for the options and determine, where to save the pipeline's results. If you are curious, how to run a pipeline with MorganaXProc's gui, you can skip this part and go directly to Running a pipeline, since "gui‑welcome.xpl" does not need any input port bindings or option settings.
To provide a document or several documents to an input port, just take an xml document from your file system and drag the icon to the zone below the port name and release your mouse button. The file's uri will show up in the port's binding list. Since the "source" port is a sequence input port, it will accept more than just one document: Just take another document's icon, drag it to the input zone (above or below the previous uri) and release your mouse button. Again the document's uri will appear in the port's binding list. If you want to reorder the documents, just click and hold a uri in the list and move it up or down, releasing your mouse button when the uri appears at the desired position. If you want to remove a uri from the port's input list, take the uri and drag it to the field labeled "‑" and drop it there. It's gone.
Now: As we are providing bindings to a sequence input port, you can also drop a folder from your file system into the input port's binding list. When running the pipeline, MorganaXProc will look up all the files with suffix ".xml" in this folder and provide them as binding to the selected input port. Of course you can be more specific about which files in folder should be supplied to the pipeline: Choose a folder in the input port's binding list and double click. The following dialog will pop up:
By providing regular expressions in the fields "Include" and "Exclude" you can select, which files are provided to the pipeline and which are not. The mechanism used here is exactly the same as in XProc's "p:directory-list". By selecting the switch "Deep?" you can tell MorganaXProc not just to look for documents in the selected folder, but also to look in folders contained in the folder and so on. For now, just close the dialog and let us go back to the visual input form window.
As we provided input port bindings by dragging and dropping files, you might ask yourself, whether it is possible to provide a binding from a source not droppable, like a document on the internet. That is exactly what the "@" field is for. Click on the "@"-field, drag it to the desired position in the input port's binding list and release your mouse key. Now the dialog, we already know from folder dropping, will appear again, this time with an empty field "URI". Here you can type in the uri of the document which will appear on the pipelines input port. Of course you can also paste a uri from the system's clipboard. Click "OK" or "Cancel" to go back to the visual input form window.
No we are done with the binding of the pipeline's input ports, let us go further down the form to the field labeled "OPTIONS". Here MorganaXProc lists all options declared in the pipeline. As you can see, the "welcome"-pipeline has just one option, called "user". This option is declared with the default value 'the user', which is shown in the option's input field in colored text to distinguish it from your input, which will appear in black. Just select the input field behind the options name and type in anything you like. The default setting for the option will reappear, if you leave the input field empty. To provide a setting for the option, you can also paste some text from the system's clipboard or drag and drop any file on the input field. MorganaXProc will take the uri (not the document named by this uri!) as value for the option.
If a pipeline has one or more options declared as required, you will not see any default values, since required options can not have a default value in XProc. To distinguish required options from others, the name of a required option will appear in bold type face. This is to remind you, that the pipeline will not run properly without a value supplied for this option. This is just an optical hint for you, since MorganaXProc's graphical user interface will not force you to supply a value here.
Now: Below the options there is the section label "OUTPUTS". All declared output ports of the chosen pipeline are listed here. In our case the ports are named "result" and "info port". Here you can provide locations where MorganaXProc will save the results produced by running the pipeline. You do not have to specify locations for the result if you do not need them permanently. But if you want them to be saved, just drag and drop any file or folder from your file system to the input line next to the port's name. Of course you can also type in a uri (starting with "file:") or paste a uri from your system's clipboard. If you drop a folder, MorganaXProc will make up a file's uri by using the port's name and the suffix ".xml".
As our pipeline has two output ports, you might want to have all result of the pipeline in just one folder. You can achieve this by dropping the same folder on both input fields next to the output ports' names, but there is an easier way: Make sure the input fields next to the output ports' names are empty and then drop a folder into the input field label "Base folder:". As you see the input fields associated with the output ports now have the same name as the port with the suffix ".xml". All results of running the pipeline will now be saved to the folder named in the field "Base folder" with the selected file names. If you change the value for "Base folder", you can provide another output target, but the filenames will be unchanged.
The last interesting setting in the "OUTPUTS"-section appears right of the input box for uris. There is a selector label "wrap?" which will be enabled, if you provide an output target for the port and the output is a sequence port. There are two ways of saving the result of a sequence port: Without having "wrap?" selected, MorganaXProc will generate a file for each document appearing on a sequence output port. These files will have a number attached to the selected filename, which corresponds to the position of the saved document in the output ports' sequence. But if you select "wrap?", MorganaXProc will produce just one file wrapping all the documents in the sequence into a new xml document.
On the lower end of the "OUTPUTS"-section you see two selectors labeled "Create folders without asking" and "Overwrite files without asking". These are meant to protect your filesystem against unintentional effects. So, if not selected, MorganaXProc will ask you before creating a folder or overwriting any file saving the pipeline result respectively.
In the previous section we talked about providing binding to input ports, setting values for options and saving results appearing on the output port. All this was done just by relying on the names of the ports and the options. But what does the option named "user" exactly stand for and how does a setting affect the result of the pipeline? Well, to be exactly sure, you have to look at the pipeline document using a text editor or a web browser. This is not always handy, so MorganaXProc's graphical user interface makes use of the documentation feature named p:documentation defined for XProc. If the pipeline dropped on the greeting screen contains any elements named "p:documentation" in XProc's namespace, MorganaXProc will read them and provide them as information for you. How can you see them? Just move your mouse to the upper colored section of the visual input form containing the name/type of the pipeline. Stay there. After a moment you will see a tooltip pop up and provide you with the information found in the p:documentation elements.
The same feature is implemented for the input ports, the options and the output ports. Just move your mouse over the name of an input port, an option or an output port. Wait a second, and the information found in the p:documentation elements under the p:input, p:option or p:output in the pipeline will pop up. If there is no documentation for any element in the pipeline, a tooltip will appear as well, just telling you that no information was found.
Need some action? Ok, then let us look at the buttons in the lower color section of the form. There you will find five buttons named "New", "Prefs", "Clear", "Save" and "Run". If you hit "New", MorganaXProc will abandon the chosen pipeline and your settings and go back to the greeting screen so you can drop another pipeline. If you hit the "Clear" button, the chosen pipeline will remain but all your settings in the form will be cleared, giving you a fresh form. And the "Run" button? You guessed it: Hitting this button will cause MorganaXProc to run the pipeline with your settings. (You can also start the pipeline to run by hitting "CMD R" on MacOS or "CTRL R" on Windows. To remind you about that keystroke, the letter "R" is coloured. You can disable this visual hint in menu "Preferences...")
We will talk about the buttons labeled "Prefs" and "Save" later. For now I suggest to hit the "Clear" button to remove all settings in the input form. Since the pipeline "gui‑welcome.xpl" does not need any settings (as already mentioned above), this will give you the chance to run the pipeline without any error message caused by missing documents. Cleared? Ok, then hit the "Run" button.
Having hit the "Run" button, MorganaXProc will compile the pipeline, provide the pipeline with your settings and run it. If you have made any settings in the "OUTPUTs"-section, MorganaXProc will try to save the pipeline result respecting the settings made for folder creation and overwriting of existing files. And it will provide you with information about this process, looking like this:
If any error appears compiling the pipeline, binding your settings to the input ports and options, running the pipeline with this bindings or saving the result, MorganaXProc will tell you in this window, what went wrong (and probably also why it went wrong). For now: If there is any error message in running "gui‑welcome.xpl" it is most certainly because you did not hit the "Clear" button before running the pipeline and so providing some binding from the tryout to the pipeline. Not difficult to cure: Just hit the "Back" button (or hit "CMD B" or "CTRL B") in the lower colored section of the window and you will see the visual input form again. Hit "Clear" and then "Run" and everything should look great.
Beside the information that everything went right, there is nothing spectacular to the window. Let us change this: Hit "Back" and then drop a folder of your filesystem on the field next to label "Base folder". Then put the cursor behind the uri in "Base folder" and add the name of a non existing subfolder and "/". Make sure the two settings "Create folders without asking" and "Overwrite files without asking" are not checked. Now, hit "Run" again.
Since you selected a non existent folder for "Output Base" and you told MorganaXProc not to create any folder without asking you first, you will now find new information in the run window: Not surprisingly MorganaXProc will tell you that it has to create a folder in order to save the result and asks for your permission. Hit the "DO" button next to "Create?" to allow MorganaXProc to create the folder and save the pipeline results. Since all results go to the same folder, you have to allow folder creation only once. If there are different folders to create, you have to give permission for each of them. The same holds, if to tell MorganaXProc not to overwrite files without asking: Instead of asking permission for creating a folder you will be asked to give permission for overwriting existing files. And again: Hit "Do" if you want the existing file content to be overwritten, do not hit the button, if you want to keep the existing file content.
Wonder what the "View results" button is for? Hit it to find out!
Hitting the button "View result" will bring up a new window, looking similar to this:
In the left column you see a list of all the output ports of the finished pipeline. In our case there are two output ports named "result" and "infoport". As you can see, "infoport" is a sequence output port with two documents named "doc-1" and "doc-2", while "result" is a non sequence output port.
In the right column you can inspect the documents produced by the pipeline's run. Initially you will see the document associated with port "result" but by clicking on the port or document names in the left column the corresponding documents will appear in the right column. If you click on the name of an sequence port, you will get general information about this port, namely how many documents are associated with this port.
With the result view you can not only inspect the documents produced by running the pipeline but you can also save the produced documents somewhere in your filesystem. Let us try it out: Click on the port name "result" in the left column, hold down the mouse and move your mouse pointer to your operation systems desktop. As you see, a small icon with a "+" will appear as soon as the mouse pointer has left MorganaXProc's window. Now release your mouse key and a new file icon named "result.xml" or just "result" (depends on your system's settings) will appear on your desktop holding the document on port "result".
Of course you can not only drag the result to your desktop but actually to any place in your filesystem, where you want the result to be stored. Just open a window for the desired path and drag the icon there. The same works for the two documents "doc-1" and "doc-2" on the sequence output port "infoport". And you can also drag "infoport" (the name of the sequence output port) to your filesystem. In this case, MorganaXProc will wrap all the documents found on that port into one valid xml document and store it on your filesystem under the name of the sequence output port. Try it: Click on "infoport", hold down the mouse key, drag it to the desktop and release the mouse key. A new file named "infoport.xml" will appear and if you open the file, you will find all the documents on that port wrapped under a common root element called "wrapper" in MorganaXProc's namespace.
Now, as you might have recognized, when saving a document to the filesystem, MorganaXProc chooses the suffix ".xml". This is not always handy, because most browsers will not recognize an html document saved with suffix ".xml" correctly. This is actually the case for "doc-1" on output port "infoport", which is (some kind of) an html document. Now click on "doc-1", drag it to your filesystem and release the mouse button. As you will see, the resulting file is called "infoport-doc-1.html", not "... .xml". This is because MorganaXProc looks into the document to save, recognizes the root element's name as "html" and therefore chooses suffix ".html". You can turn off this feature by deselecting "Guess extension for save?" in the preference dialog in the menubar.
With this, we are done with exploring MorganaXProc's graphical user interface. But, as you might remember, there are two open points, namely the buttons "Save" and "Pref" in the lower colored area of the visual input form.
As you have seen, in the visual input form you can bind documents to input ports, set values for options and tell MorganaXProc where and how to save the results appearing on the output port. Sometimes it might be useful to be able to save these settings for another run of the pipeline at some later point in time. This is, what the button "Save" is for: It lets you save all the settings in the visual input form in a file for later use. If you hit the button, a file selector box will appear letting you choose a location.
If you want to use these settings, just drop the icon of the file on MorganaXProc's greeting screen instead of a pipeline icon. MorganaXProc will then open the pipeline associated with the settings and the settings as well and show you the visual input form with these settings. And if you change anything and hit the "Save" button, your new settings will be saved without a file selector box.
Note: As the pipeline and the settings for running the pipeline are strongly interconnected, there might be a problem with reloading visual input form settings when the pipeline has changed in the meantime. For example you might have removed or renamed a port, added some options and so on, making the savings and the pipeline incompatible. So when dropping saved settings of a visual input form on MorganaXProc's greeting screen, MorganaXProc will automatically check the settings with the current version of the pipeline and adapt the settings, so the pipeline can be executed with these settings. This might lead to some loss of information, for example if you rename a port, because MorganaXProc will remove all bindings for the old port's name. This will not always be the result you would expect, but it keeps the pipeline always runnable. And this seems to be a strong argument.
With the "Pref" button in the lower color area of the visual input form and the Preference menu item you can configure MorganaXProc's behavior while compiling and running pipelines. The mechanism used and the meaning of the individual settings are discussed in Understanding Options In Configuration. What we need to discuss here is the difference between the settings controlled by the "Pref"-button and those controlled by the menu item. And we have to understand how to control MorganaXProc's settings using the graphical user interface.
Point one: What is the difference between using the button "Pref" and using the menu item "Preference". Shortly, they will influence the MorganaXProc's compiling and running XProc pipelines on two different levels. With the button you can only control the settings for running the recent pipeline, while the menu item will control the settings for all pipelines. As explained in Understanding Options In Configuration, MorganaXProc has a cascading configuration process. Using the menu item you can set the preferences on level 2 (edit the file "xproc-config.xml") and with the button "Pref" you can control level 3, just applying to the recent pipeline.
Point two: How to control configuration with MorganaXProc's graphical user interface? Let us go back to the visual input form and hit the "Pref"-button. The following dialog will appear:
In the top row you see different groups of settings organized under the names "General Settings", "Security Settings", "Wrapper Settings" and "Extension Settings". Below is a list of settings, each row having the name of the setting, its current value and a reset button. As you see, all of the setting values are greyed out and in italic font face. This tells you, that you have not set the value for this setting on the current level, and the value shown represents the value set one level deeper. To change a setting's value, just double click on the text field. It will activate and turn to plain font face. Now you can put in the favored value for the setting. If you want to restore the setting to the value set on the more basic level of configuration, just hit the "Reset" button in the appropriate line. The value, you typed in, will disappear, the font face will turn italic again and the default value for this preference will appear in the text field. To save your changes, hit the "Ok" button, to discard your changes, hit "Cancel".
If you choose the menu "Preference" from the menubar, the same dialog as with the button "Pref" will appear, but now you are able to edit configuration one level deeper in MorganaXProc's cascading configuration process. The settings made in this dialog box do apply to all pipeline runs with MorganaXProc and are therefore more basic than the settings made using the dialog connected to the button "Pref". Additionally, in the dialog box connected to the menu "Preferences" you will find some settings to control the GUI's behavior and appearance.