Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Writing Examples

This document walks through the process of creating an example using the new format.

Creating the Code

We create core concept examples using Mule Studio and the code is stored in GitHub:

I couldn’t find an integrated way to work with Mule Studio and GitHub, so the approach I have taken is the following:

  1. Check out the GitHub repository into a local directory i.e. /projects/github. You cannot have MuleStudio (Eclipse) workspace in the same location.

  2. In Mule Studio, create a new workspace for working with the examples. Go to File -→ Switch Workspace -→ Other

  3. You can import the existing example projects into this workspace, go to File -→ Import -→ Mule Project.

  4. To create a new example, go to File -→ New -→ Mule Project

  5. Set the name of the project to the name of the example being created, keep all the letters lower case and use a dash '-' instead of spaces. Click Next

  6. Make the flow name the same name as the project and click Next (don’t click finish)

  7. Chance the default project location by unchecking the 'Use default location' and then create the project in the same directory as the local copy of the GitHub repository i.e. /projects/github/core-concept-examples/new-example

  8. Click Finish

  9. Create the example in MuleStudio. When you are ready to commit something to GitHub open a command shell

  10. go to the GitHub local repository directory and run 'git add new-example'

  11. then run 'git commit -a -m "initial commit"

  12. You can keep making local changes and committing to the local repository using the 'git commit' command

  13. When the code is complete, execute 'git push' to push your new example to the remote repository

Create Example Page

To create a new example page:

  1. At the bottom-right of the page, select Edit -→ New -→ Page

  2. Give the page a descriptive name, this name will be used in the navigation

  3. There is a link at the top of the new page screen called "Select a page template to start from", click this.

  4. Select the "Example Page"

  5. You can start filling in content on the template, but I find it easier to click "Insert Variables" at the bottom and start editing the page directly.

Example header

Each example has a header section that needs some information. The formatting is wrapped in a confluence macro that looks something like:

{example-header:mf-name=introduction-to-endpoints|timing=15|image=echo-flow-100.png|screencast-link=ScreenCasts#introduction to endpoints}

You just need to add the following fields:

  1. image - the left hand image for the example. This image should be no more than 100x170px. If the example is a large flow, just show a part of it.

  2. mf-name - Deprecated.

  3. timing - Time in minutes it takes to run through the example

  4. ion-link - the URL of the example running on iON, this is optional

  5. screencast-link - this is optional. IF you create screencast, you should upload to YouTube (contact Ross for the account to upload to) and embed it in the page. Right above the screencast add a {anchor} macro that will be used to link directly to that screencast.

Content

  1. The Introduction should be written from a user perspective not a Mule perspective. It should only introduce one or two concepts at most.

  2. What you will learn section should just be 2-4 bullet points that summarize the key learning points

  3. Prerequisites - If this example builds on s previous on, oyu need to link to the previous (or base) example. If not, you can just embed the page using {include:Prerequisites}.

  4. Building the Example - This is where you include step-by-step guide of what a user needs to do you create the example themselves

  5. Running the Example - This section details how to run the example, typically it is short, there is no need to add screenshots for each step unless something changes for the current example (i.e. run on iON or from Maven)

  6. What just happened section is a recap of what the user did highlighting anything that wasn’t explicit in the actions performed (i.e. Adding an inbound endpoint to a flow creates an HTTP server, or explaining how the hello component actually got invoked).

  7. References - should contain all links to content from the rest of the post and any other links that may be useful for the reader

Next steps

Where possible our examples should build on each other, creating a path for users to follow. I have created a macro for generating the navigation buttons at the bottom to move through the path. You need to pass in 3 pages for previous, index and next:

h2. Next Steps{flow-nav:previous=Foo|index=Home|next=Adding Message Processors to a Flow}

These are page names of other examples in the examples space. If there is no "previous" (because you are at the beginning of the trail) or no "next", just leave those parameters out. The "index" param points to the landing page of the example trail.

Screenshots

Screen shots should added for every new step. If you are working on a building example - such as a Core Concepts example like Adding Business Logic to a Flow - don’t add screenshots for steps already covered previously unless the details change in some way.

To add a screen shot you need to wrap it in a div to give it consistent formatting:

{div:class=screenshot}!studio-file-new-project.png!{div}

As you are writing the page you will not have the screenshots attached to the page. I find it easier to write up the content first and leave placeholders for the images, then attach the images to the page and edit any placeholders to reference the right image.

Screenshots and any other images are attached to the page. To do this go to the bottom right edit menu and select "Attachments".

When working with attachments I find it easier to have the attachments page open in a separate window to the example page I’m editing so that I can easily cut and paste file names and upload any screenshots I might have missed.

Page Organization

Make sure that your example age is a child page of the correct parent i.e. the landing page for the example group. If you need to move pages around the bast way to do it is to go to the bottom-right menu, select View -→ Other Pages -→ Site Map. This shows a tree where you can drag and drop pages in the tree and set the order of pages.