I Accidentally My Business Cards With Gears

Posted by admin on July 22nd, 2014 filed in Steampunk
Comment now »

You know your hobby is mainstream if… Stationary shops sell ready-made scrapbooker stamps with that theme! ;-)

steampunk stamps

Behold. I didn’t know people were into stamps that much? Very steampunky indeed. Though many of these make no sense what so ever. :-D A watch inside a pennyfarthing bike? A clock wearing a top hat? A metronome with a swallow attached to it?! And a camera, a suitcase, a bottle, an Eiffel tower, and an airship… all studded with gears… :-)

Don’t know yet what I will do with them. Wasn’t planning on making a scrapbook. I’ll experiment on paper (some of the paper might accidentally be… *cough*business cards*cough*), and also with textile-prove paint on cloth and leather.

Source:


A Small ToDo-Tracker

Posted by admin on July 20th, 2014 filed in Uncategorized
Comment now »

Looking for an online ToDo tracker for a small team? Try Red Booth, it’s got good mobile app support, and is free.

I was looking for a simple offline ToDo List tracker on Sunday, so I tried Kanboard, which has very similar features. Kanboard is free, very light-weight (2MB), platform-independent, easy to install, self-hosted, and minimalistic (as in, it has only the most essential features). Kanboard is based on the Kanban board method.

The main idea of a Kanban board is to visualize the workflow. Typically, projects are delayed or fail because you underestimate the workload, and overestimate yourself. A Kanban does not prevent delays or project failures. However, a Kanban enables you to detect impending “doom” as early as possible. As soon as you see that you cannot complete a job in time, you can react and adjust your plans.

Kanboard Features

Your Kanboard can accomodate several users and track several projects. You split your work into projects, tasks, and subtasks.

  • Each project has custom categories and custom status columns. Projects contain tasks.
  • Each task is in one category, and has a description and a status. It has a due date and duration, one owner and one color, attachments and comments. Tasks contain subtasks.
  • A subtask is one line of text. Its status can be Todo, In Progress, or Done.

That’s it! No frills.

Kanboard Installation

Kanboard requires a PHP-enabled web server, such as Apache. You need to install this server and know how to manage its web root on your system. Depending on your experience level, this is the only complicated step.

  1. Activate the web server and PHP support on your localhost. (For example Apache on MacOS)
  2. Download the zip file from http://kanboard.net/
  3. Expand the zip file, and move the resulting “kanboard” directory into your web root directory.
  4. Make the “kanboard/data/” directory writeable for your web user (there is probably a more secure way to do this, but the following works):
    cd kanboard/ 
    chmod a+w data/

Setting Up Kanboard

  1. Access kanboard in your browser under “http://localhost/~username/kanboard/”. (The actual URL depends on what your localhost Apache URL, your username, and kanboard directory name is).
  2. Log on to kanboard with the admin/admin default account.
  3. Change the admin password.
  4. Create a user account for yourself (and possibly others).

Creating Projects

A good project is something concrete that has clear criteria. For example, “Install shelves in garage” or “Grow vegetables” are better project ideas than the very generic “Household” or “Gardening”.

  1. Access your Kanboard and log on as admin.
  2. Click Projects, click New Project, and provide a project name.
  3. Click Edit Board in the project list if you want to define custom status columns. Otherwise, keep the default status columns: Backlog, Ready, In Progress, Done.
  4. Create custom categories for your project.
  5. Back on the Admin’s Projects page, specify “Automatic Actions”!
    Kanboard offers simple but useful if-then event handling for each project. For example, “if ‘task creation’ in ‘backlog’, then ‘assign task to person who did the action’”.

Tip: Think of categories and colors as mutually exclusive subdomains of one project: Each task can be in one category only, and be tagged with one (of 7) colors only. Categories allow you track several simultaneous hobbies in one project, so you can compare the time you will spend on all of them. If you engage in two hobbies but track them in separate projects, you defeat the tool’s purpose of visualizing your overall workload (and you’ll accidentally allocate yourself 200%)!

I haven’t decided yet what I want to use the colors for – most likely priority/urgency levels. If you track teamwork, you can also assign a color to each team member via Automatic Actions.

Adding Tasks

If you kept the defaults, your project has four status columns for tasks:

  • Backlog: Your queue of open incoming todo items. They are possibly unassigned or non-urgent, are missing done-criteria or subtasks, or have no due-date yet. This column is typically very long.
  • Ready: Todo items that you intend to work on in the current time frame. They are important or urgent (due-date), and you have defined done-criteria and subtasks for them.
  • In Progress: When you start working on a task, move it here.
  • Done: When you’re done, move the task here. The project is done when all its tasks are done.

Break down the project into tasks and subtasks. Define each task with the thought that a task has a “result that you could show to someone”. Analyzing the problem, completing prerequisites such as readying parts and ingredients, designing a draft/boilerplate/pattern/stencil, or testing whether the “result” truely works, are just as valid tasks as the steps of the actual execution. Each step of the task is a subtasks that you describe in one line.

  1. Access Kanboard and log on as user.
  2. Open a project. Click the Plus button for the Backlog to add a task.
  3. Name the task. Under Description, describe the goal (what problem you are trying to solve), the stakeholders (who benefits, who is impacted), the method (how you want to solve it), prerequisites, and done-criteria (how you know that the task is complete).
  4. (Optional) Set a category and pick a color for each task.
  5. (Optional) Open each task, and add subtasks (one line of text each).
  6. (Optional) Add additional materials as attachments: Diagrams, drawings, recipes, videos, Excel tables, instructables, or related links.
  7. Drag and drop the task higher or lower in the backlog to express its priority.

Kanboard Workflow

While you plan and work, you switch subtask states from “todo” to “in progress” to “done”. When all subtasks are done, the task is done. You can update a task’s status quickly by dragging and dropping the task into the next column.

In Kanban, you do not only get tasks “Done”. You also regularly pull tasks from the “Backlog” and get them “Ready”. Similarly, you sometimes have to limit yourself, and return unfinished tasks to the “Backlog”.

  • If the “Ready” column is empty, define the missing properties of a high-priority “Backlog” item, and pull it into “Ready”.
  • If the “In Progress” column is empty, pull a high-priority item from “Ready”, and start working.
  • If the “In Progress” column doesn’t fit on one screen, you are slowing yourself down by multi-tasking too much. Time to re-focus! Limit yourself by returning low-priority tasks to “Ready”.
  • If the “Ready” column doesn’t fit on one screen, you have overtasked yourself for this time period. Limit yourself by returning low-priority tasks to the “Backlog”.

I assume you could also track cyclical projects, where all “Done” items return to the “Backlog”. This type of project would never be fully “Done”, you merely use it to track the status of a recurring workflow.


Start a Web Server on Your Mac

Posted by admin on July 19th, 2014 filed in Mac
Comment now »

Sometimes you want to preview some web content locally on your Mac. Maybe you want to browse a backup of your home page or blog, or you want to run a local web application.

In previous versions of MacOS, you simply activated Personal Web Sharing in the control panel, and you could access the content of “Users/yourname/Sites” in the browser. This option is gone in the current MacOS. The web server however is still installed. You just need to know how to switch it on. :-)

  1. Open the Terminal.app and enter
    whoami

    Remember the response, this is your name that you need to replace in the path and the URLs below!

  2. Start the web server by entering the following command (it will ask for the admin password):
    sudo apachectl start
  3. Open the Finder and copy your web content to “/Users/name/Sites/”. It’s okay to create subfolders under “Sites”.
  4. Open your web browser (by default, Safari) and browse to your local web URL (note the tilde):
    http://localhost/~name/

    You should see an index page or folder listing.

  5. To access a file such as “/Users/name/Sites/page.html”, or a directory such as “/Users/name/Sites/subfolder/”, the URLs look as follows:
    http://localhost/~name/page.html
    http://localhost/~name/subfolder/

If the webpage in question contains PHP files, they may show up as PHP code in the web browser instead of being executed. In this you need to activate PHP too.

  1. Open the Terminal and edit the following configuration file.
    sudo nano /etc/apache2/httpd.conf
  2. Search for lines that contain the word “PHP”. By default, they are commented out by a “#” character.
    #LoadModule php5_module libexec/apache2/libphp5.so
  3. Remove the “#” character and save the file.
  4. Restart the web server.
    sudo apachectl restart
  5. Reload the PHP page on your localhost in the web browser.

PHP is activated until you comment the line out again. The apache webserver however is not permanently on — it doesn’t start itself after you reboot. PHP depends on the webserver, this means, you need both. I prefer to start thr webserver manually right when I need it, and leave it switched off otherwise.


Some Nice Engrish I Found in the Deutsches Museum Shop in München

Posted by admin on June 29th, 2014 filed in Linguistics
Comment now »

SPACE RAIL is a suit-toy which could be assembled freedom with the base, SHAFT and RAIL… the STEEL-BALL could run on the two RAILs sometimes snail and sometimes scour, it is for adult playing indoor, you could assemble protean RAIL with your imagination, the main part of SPACE RAIL is four loops (STEEL-BALL run through the four loops one by one then enter into lift stage) also, it included some cliff-hanging part such as “big revolving part” and ‘stunt parts” etc, these special parts will catch the high-level player interest.

… What? :D

The box contained a customizable rollercoaster for marbles, made in China. Aha!

The “sometimes snail, sometimes scour” line has got a certain “cliff-hanging” je-ne-sais-quoi. It’s cool that “it is for adult playing”, if you know what I mean. … … Actually… I don’t know myself what I mean. How would that even work?? ;-)


Cleaning Clockwork

Posted by admin on June 21st, 2014 filed in Steampunk
Comment now »

Real clockwork gears look nicer in steampunk costumes – but they are harder to work with. Many gears have long prongs or sharp spikes that limit how close to your body you want to wear them ;) Others are solid metal and there is no obvious way to attach them. I started out by sorting my gear collection into roughly four categories:

  • Large flat wheels with gaps (necklace);
  • Tiny fragile wheels (need a foundation, not too exposed, maybe on hat or bracelet?);
  • Tall funky wheels (stylish hat decorations?)
  • Wind-up keys (pendants);

This photo is a partial closeup of the broken clockwork straight off the fleamarket. A lot of rust and patina, but nice unique shapes and materials that you don’t get when you buy “100 Assorted Wholesale Steampunk Gears”. Mental note: Must repress the urge to wash metal with water… =-)
steampunk_gears_fleamarket

I found a nice kutilství (crafts and DYI) shop and asked for an anti-corosive agent. They recommended a cheap locally-made cleanser called Silichrom. You put a layer of this paste on the metal object, wait a bit until it dries, and then remove the paste. I used an old toothbrush (and wooden toothpicks) since most gears had odd shapes and I could not easily wipe off the surface. Silichrom removed most of the rust and patina, although I sometimes had to apply it twice for full effect.

steampunk_polishing_gears

The important step is to polish the metal with a soft cloth right after the application. I used a simple viscose cloth and some q-tips (and rubber gloves). Don’t use your favorite dish cloth (nor you favorite rubber gloves), because rust leaves drastic stains. :p The gears look nice and shiny now! Only close up you see some scratches.
steampunk_gears_polished

I already started working on a necklace, a kind of Charivari-style clockwork collar with keys as pendants. :-) The central gear looks super awesome, and I even got it unstuck, which means I can rotate the inner wheel in one direction, and the ratchet clicks into place.
steampunk_gears_jewelry
You see that this is where I used all the flat large gears. I had to cut off two prongs of the central gear with a hacksaw though. Next I need to cut and attach the chain, and decide what kind of fastener I want, but decisions about the collar’s chain depend on how it fits to the costume’s bodice.
steampunk_bracelet_planning_stage
Since the kutilství shop also happened to offer leather belts, I also started planning a clockwork bracelet. This photo shows the planning stage, where I aligned the gears with bracelet holes. I want add two thin metal chains first before I attach the gears though.

To be continued…


Cool Steampunk Accessories from the Fleamarket

Posted by admin on May 10th, 2014 filed in Steampunk
Comment now »

In order of coolness, here’s some stuff I bought at fleamarkets that make good accessories for a steampunk airship engineer costume.

Waterlevel, Wasserwaage, Heinrich LANZ AG This was sold as a “100-years-old” water level (Wasserwaage) at a fleamarket in Berlin. The text was not readable before I cleaned the area around the air bubble’s vial.

The writing says “LANZ Separatoren mit Neusilbereinsatz sind die vollkommensten”, i.e. “LANZ separators with nickel silver inset are the most perfect”. It’s an advertisement for the (no longer existent) German company “Heinrich Lanz AG Mannheim”. This company produced steamengine vehicles and airships in the decades around the year 1900!! Their coolest vehicle was the “Lokomobile”, a steam tractor used by farmers. Wow, this small antique is better than I had expected. Nothing is more Steampunk than (an advertisement for…) Lanz. :)

weird orb steampunk pocket watch I don’t know where these “orb” pocket watches are coming from all of a sudden? Probably a modern company mass-produces them, knowing that dumb Steampunks like me will buy them, although it says Quartz… (Admittedly, the first Quartz clocks were invented in 1930 — but they surely did not look like that.)

This particular piece of junk from the Berlin fleamarket displays Central European Gravitational Time. What is gravitational time, you ask? When you pick the watch up, both hands point to the closest source of gravity…! :-(

The watch contains clockwork and a battery, but it’s so cheaply made that the two hands are too weak to move independently, much less “uphill”. Oh well. It looks steampunkish enough for now, until I find something better.

steampunk lapel pin and badge This pin and badge are the best pin and badge ever! <3 One Euro per piece from the Prague Kolbenova fleamarket.

The lapel pin spells out "FS", which stands for "fakulta strojní" (engineering department). The F is a calliper and the S is two cogwheels! Very engineer-like. And the button badge is a super cool Jules Verne-style spaceship! Whee!

letov pin

The third pin is a little airplane / sword labeled Letov. Letov is short for “letadlo” + “tovarna”, meaning airplane factory. The Czechoslovak plane company Letov existed in the 1920s, so the pin fits the 1900s/Steampunk theme well.

I have no idea what these pins were produced for, but the fleamarket sure has lots of them. Is it an “congrats, employee of the month” kind of thing? In any case, if you look hard and dig through a box, you find some that work as improvised imperial aetherforce badges on your steampunk jacket. :-)

Steampunk pins: technometra, laborator, elektrokov, 2x tesla The next five are the best of the rest of the handfull of pins I got. They say, from left to right, top to bottom: “Technometra Benešov”, “Elektrokov Trutnov”, “Tesla Strašnice Závod Votice”, “100 let laboratoří VTŽ VŘSR”, and “Tesla Karlín”.

You can tell that I simply picked pins with words that sounded appropriate for an engineer. Four of the pins are from factories in the Czech Republic, followed by the name of a city or department. The same Tesla logo also features prominently on a stained glass window in Prague’s Svetozor passage. :-) The larger pin is for the 100-years anniversary of “laboratories”, but the seller could not tell me what “VTŽ” or “VŘSR” means. I found hints that VTŽ stands for ironworkers (“válcovny trub a železáren”), and VŘSR might be the abbreviation for the October revolution. *shrug*

I purposefully avoided pins that looked political, but abbreviations can get me. You gotta watch what you buy, they do sell pins at Kolbenova that would be “frowned upon in Germany”, if you know what I mean. Oh, and I got another one (not depicted) that turned out to say something about an insurance company. Not Steampunky enough. ;-)

cogwheels (clockwork) - Zahnräder (Uhrwerk) Hah! I just had to buy this! An old box with a smashed clockwork for ~2 Euros. Or several smashed clockworks? There are 4 hands in total.

The box contained two dozen cogwheels of different types, four wind-up keys, a few springs and pullsprings, and some tiny screws. (And some small broken things that surely had their purpose in a watch, but were not salvageable.)

The large item in the top right still has a pull spring and a tiny lever that gets pulled back. *presses lever!* :-) *lever pulls back* … *nothing more happens* :-(

Mysterious clockwork parts Are clockworks propelled by tiny horned dragons? :-o What are these things? They were also part of the clockwork.

Hmm… Maybe the moose antlers hold on to that one barbed wheel? …

What ever they are, I will find some good Steampunky use for them. :-)


Confluence Plugin Development – Troubleshooting

Posted by admin on May 3rd, 2014 filed in Java, Wiki
Comment now »

When I develop a Java project, I rely heavily on IDE tools for refactoring, syntactic and semantic highlighting, debgugging, profiling… I also clean, build, and run the app often to test workflows and spot whether a change broke something.

When I develop Confluence Plugins however, I have the added factor of rebuilding and installing the plugin into the confluence server. Even worse, IDEs won’t recognize the Confluence project structure and won’t know how to refactor it. So you are facing weird plugin behaviour that doesn’t go away by pressing F5 really hard. What happened?

Maybe FastDev did not reload the plugin – maybe you didn’t save one of the files before rebuilding – maybe you used a wrong key – maybe you never truly told the project to link that Javascript or SOY file – maybe you made a typo in the POM – maybe your IDE “helpfully” modified the POM behind your back… What ever the problem is, the Confluence log output is not very explicit about the source of the issue.

Here’s some generic tips for troubleshooting Confluence Plugin development:

  • Use you Atlassian ID to search, and ask and search questions on https://answers.atlassian.com/
  • Browse a search documentation on https://support.atlassian.com/customer/home
  • If you notice a large jump in disk usage in the target directory, or if atlas-run or atlas-package suddenly take, say, half an hour instead of 2 mins, something is awry.
    For example, for the main Confluence dependency in your POM.xml, the scope must be “provided”, because Confluence is provided in the SDK. No need to download it every time! Your IDE might mess with this setting, so keep an eye on it.

    <dependency>
        <groupId>com.atlassian.confluence</groupId>
        <artifactId>confluence</artifactId>
        <version>${confluence.version}</version>
        <scope>provided</scope>
    </dependency>
  • Do not use the standard Java logger (nor println…) for debug output. If you do, the output doesn’t go anywhere. Use the slf4j logger instead (as shown in the Confluence skeleton code), slf4j routes the output into the terminal and log files.
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    ...
      private static final Logger LOGGER = LoggerFactory.getLogger(MyJavaClass.class);
      LOGGER.error("I haz a problem", e);
  • Find logs for the Confluence main installation here:
    C:\Program Files\Atlassian\Confluence\logs
    C:\Program Files\Atlassian\Application Data\Confluence\logs
  • Find logs for your plugin’s temporary Confluence instance here (…not useful?):
    C:\Users\YOURHOME\Documents\AtlassianProjects\kbarticle\target\container\tomcat6x\cargo-confluence-home\logs 
    C:\Users\YOURHOME\Documents\AtlassianProjects\kbarticle\target\container\tomcat6x\apache-tomcat-6.0.20\logs
    
  • You can create a remote debug target in most IDEs so you can debug Confluence. — I haven’t tried that yet, but I’ll report back how it went. :)

I’ll add more tips as I discover them.


Confluence Plugin Development in NetBeans

Posted by admin on April 27th, 2014 filed in Java, Wiki
Comment now »

Atlassian recommends using Eclipse for Confluence Plugin Development, but I already had NetBeans 8 installed, so in the following I’ll write about how that worked out.

NetBeans IDE supports Maven projects, but Confluence plugins rely on several frameworks, not all of which NetBeans handles out-of-the-box.

Don’t Listen to Outdated Atlassian Docs :-P

First, ignore Atlassian’s Configure NetBeans to use the SDK advice to modify the POM.xml for NetBeans. The doc advises to add some repository configuration, which is unecessary and counterproductive: Adding the suggested properties increased the generated plugin file size from 1MB to 65MB for me, and the plugin could no longer even be loaded by Confluence. Compiling a small plugin should take < 2 minutes, and the JAR should be in the kb range, otherwise something is off. Other users also warn against this outdated advice in the comments under the doc.

Creating a New Project

The Atlassian SDK includes Maven-based commandline tools. Main tip: Don’t use NetBeans to create a new Maven project wen you develop Confluence plugins.

As all Confluence tutorials tell you, you create a Confluence plugin in the Terminal by running the create-atlas-confluence-plugin command. This atlassian SDK tool creates a skeleton project and asks you interactively for properties (such as projectid for the project name, etc).

Configuring NetBeans Maven Support

In NetBeans, I recommend the following project setup:

  1. Go to Tools -> Plugins. Make sure that you have the Maven and Java SE plugins.
  2. Go to Tools -> Options -> Java -> Maven. I configured the Maven home by browsing to the same Maven directory as the Atlassian SDK is using (your MVN_HOME variable minus the bin…bat part). You can switch the SDK to a more current version of Maven and also use it here.
  3. Important: Click “Index now” and wait.
  4. Open the created skeleton project in NetBeans: The IDE recognizes it as Maven Java project (it detects the POM.xml file) and the project appears in the Projects directory.
    Tip: If you see “unloadable”, read “Troubleshooting” below.
  5. Familiarize yourself with the following project directories: Source Packages (contains Java files), Other Sources (contains xml, soy, JavaScript, localizable strings, etc), Dependencies (overview of your Maven-controlled dependencies), and Project Files (contains the official POM.xml, and your personal NetBeans properties).
  6. Right-click Dependencies in the Project window, and tell NetBeans to download Javadoc. Wait.
  7. Open the Project properties, go to Sources, and select UTF-8 Encoding (this makes NetBeans modify the POM.file). Also note that Confluence does support JDK 7, even though the POM.xml says “1.6″ by default. You can change the JDK here too (again, this makes NetBeans modify the POM.file)
.

Setting Up the Clean/Run/Build Buttons

NetBeans uses default Maven goals for actions such as clean and build. For Confluence Development, however, you want to use Atlassian’s atlas-mvn tools and goals. For example, you run atlas-package instead of some default mvn build goal. Here’s how I replaced NetBeans’ default maven run goal by the corresponding atlas-mvn command:

  1. Open the project properties, go to Actions, and select ‘Run Project’.
  2. Under ‘Execute Goals’, enter
    com.atlassian.maven.plugins:maven-amps-dispatcher-plugin:4.2.20:run
    Note: 

The version number depends on the most current release of the SDK, check which version you are using in atlas-version.
  3. I redefined the build goal as package (instead of install).
  4. Similarly, I redefined the clean and build goal as package clean (instead of install clean).

Now Pressing F6 in the IDE builds the plugin and runs Confluence.

Running a Confluence Server From NetBeans

NetBeans builds and packages the plugin, builds and runs the Confluence server (takes a long while the first time), and installs the plugin. From here on the behaviour is the same as the official atlas-run tutorials.

As soon as you see “started successfully” in the NetBeans Output window, you switch to a browser.

[INFO] confluence started successfully in 633s at http://localhost:1990/confluence
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit
[INFO] [talledLocalContainer] INFO: Server startup in ... ms

I use Firefox which also has web dev tools (shift-F5). Browse to the above localhost path to access your temporary Confluence instance. Your plugin is already bundled in it! See my other blog entry about Confluence FastDev for (generic, not NetBeans-related) Confluence development tips.

Tip: Don’t click Stop in the NetBeans Output window, this does not shut down the server process. Type ctrl-D in the output window to prevent your Memory filling up with half-forgotten Java processes.

Use Built-in File History and Diff

When developing Confluence plugins, you typically install the plugin, and go through a longer workflow (create a page from a blueprint, use a macro in the editor, etc) to test the latest feature you added. If you notice later that one of your changes broke the plugin, NetBeans can help you revert to a previous version of your code.

You do not need to set up external file version control, since NetBeans built-in File History is integrated into the Editor window. NetBeans automatically creates a snapshot every time you save a file, so you can compare file versions and revert individual changes easily. You toggle between editor and history by clicking the Source and History buttons.

You can even compare one of your project files with another file that is not part of any NetBeans-loaded project. This is handy when you are learning from downloaded example code.

  1. Open the Favorites window.
  2. Add your project, as well as the sample project, as Favorites.
  3. Ctrl-click to select the two files to compare.
  4. Right-click the selected files and choose Tools -> Diff to get a great visual comparison and merge tool.

Similarly, to undelete a file, right-click the directory it was in and choose History -> Revert Deleted.

Configuring Colors in the Output Window

A small but avoidable pet peeve of mine: I don’t like that in the NetBeans Output window, Warnings are highlighted with a yellow font on a white background. It makes warnings quite hard to read.

  1. So off to the Tools -> Options menu we go. The important thing to know is that the “Fonts and Colors” tab only contains options for the code editor.
  2. You find the Output windows‘s settings under “Miscellaneous”! To find them, you can alternatively enter “output” into the options search box (the top right), or right-click the Output window and choose “Settings…” (Note that you can only right-click if there is output in the Output window.)
  3. Here I customized this so-called Orange to a darker shade [255,64,0].

Confluence Plugin Dev With NetBeans – What Doesn’t Work?

NetBeans 8 has no support for Soy files. Confluence Blueprint plugins use SOY templates to define wizard panels. You can open and edit them in NetBeans alright, but you will get useless HTML syntax warnings. Also the standard HTML syntax highlighting will only be partially meaningful.

Tip: Hover the yellow warning icon in the very first
 line of each SOY file. Then click the yellow warning to disable HTML checking.

Refactoring doesn’t work for Confluence plugins projects. NetBeans knows Java, it knows CSS, it knows POM.files, it knows project.properties files. However it doesn’t know anything about the structure of a Confluence plugin project, nor how Confluence weaves its pieces together through keys and the atlassian-plugin.xml file.

Tip: Unless you merely refactor a private method or field in a Java class, you have to use “Find…” on the project and refactor manually. Don’t forget that when you rename a file, you must manually update the reference to it in the atlassian-plugin.xml file.

NetBeans messes with the POM.xml file and can break it. :( The NetBeans Maven support politely offers to fix missing imports and search Maven dependencies for you. If you accept, this may change (and break) the scope of existing dependencies in the POM.xml file. Mainly, NetBeans really likes to overwrite this <scope>provided</scope> line here with <type>jar</type> which doesn’t work.



        <dependency>
            <groupId>com.atlassian.confluence.plugins</groupId>
            <artifactId>confluence-create-content-plugin</artifactId>
            <version>${create.content.version}</version> 
            <scope>provided</scope> 
        </dependency>

Warning: Every time you get weird build failures and vague complaints about Beans, make sure that the confluence-create-content-plugin dependency’s scope is still “provided” by the SDK.

Troubleshooting Unloadable Maven Projects

First tip: Before you do anything in the IDE, clean and package the plugin from the command line at least once, to exclude basic sources of error. Only if that succeeds and you know that the skeleton plugin is set up correctly, continue in the IDE.

When I opened a fresh skeleton project for the first time, NetBeans declared the Maven project unloadable and warned “…project could not be loaded… something is wrong with your POM”.

  1. Cancel out of NetBeans’ offer to resolve project problems. We want to start by fixing the POM.
  2. Open the NetBeans Favorites window. The Favorites window lets you open any text or image file outside a working project.
  3. Right-click in the window and add your project directory as Favorite.
  4. Open the POM.xml and look for yellow warning marks in the editor.
  5. Ignore the warning for <packaging>atlassian-plugin</packaging> — this line is actually correct!
  6. If NetBeans points out a missing version property for the Maven SDK configuration, find out the version of your Maven client (Tools -> Options -> Java -> Maven in NetBeans, or run atlas-version on the commandline). Add the Maven <version> to your POM as follows:
        <build>
            ...
                <plugin>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>1.6</source>
                        <target>1.6</target>
                    </configuration>
                    <version>2.5</version>
                </plugin>
            </plugins>
        </build>

    See also: Confluence Plugin Version Resolution Exception.

  7. Generally, verify everything here that has a version number in it, and make sure it fits your reality. The skeleton is likely outdated.
  8. Finally, right-click the project and select Project Properties. Tell it to Resolve Problems. NetBeans runs a priming build that should make the Maven project loadable.


First Things to Do in a Confluence Skeleton Plugin

Posted by admin on April 19th, 2014 filed in Java, Wiki
Comment now »

Here are the first things I do right after creating and testing the skeleton project of an advanced Confluence Bluepint plugin.

In atlassian-plugin.xml (the plugin descriptor), do the following:

  • Here you link an icon and logo in the <plugin-info> element. Copy your organization icon and logo PNG files to the “images/” directory (as you see it done in the skeleton project).
  • Be aware for the future that, every time you add an XML, Soy, Java, or JavaScript file, you have to declare that here. I’ll go into more detail in another blog article.

In the pom.xml, do the following:

  1. Specify your organization name and url.
        <organization>
            <name>Company Inc</name>
            <url>http://company.com/</url>
        </organization>

    Here is also where you set the plugin version from SNAPSHOT to 1.0 when you release it.

  2. Add your current maven-compiler-plugin version. Run atlas-version to find out what it is.
    
            ...
                <plugin>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>1.6</source>
                        <target>1.6</target>
                    </configuration>
                    <version>2.5</version>
                </plugin>
            </plugins>
        </build>
  3. I set the confluence version property to a stable release (5.3). By default it was a dot release (5.4.3 or 5.4.4) which threw lots of errors for me for some reason.
  4. Apparently the plugin’s <name> is lost by the wizard and not set in the skeleton, so I retyped it.

In the XML, SOY, and Java files, do the following:

  1. src\main\resources\kbarticle.properties — Define all static UI text using Java-style .properties resourceBundle files. UI text includes text in wizard dialogs (dialog-wizard.js), wizard error messages, placeholder text, the page template (article-template.xml), the plugin name, and description. Using ResourceBundles consistently will make localization and text changes easy later.
  2. src\main\resources\soy\article-wizard.soy — Here you define the form fields of the wizard UI. You link input fields to Java context variables through the “name=” attribute.
    In the following example, the text field with id customername is linked to the Java variable customerName. The static text is defined in the .properties file as my.blueprint.form.label.title.customername.

    {namespace MyPlugin.Blueprints.Simple}
    /**
    *  A simple wizard form that accepts a person's name
    */
    {template .page1Form}
        <form action="#" method="post" class="aui">
          <fieldset>
            <div class="field-group">
                <label for="customername">{getText(
                    'my.blueprint.form.label.title.customername')}</label>
                <input id="customername" class="text" type="text" name="customerName">
            </div>
          </fieldset>
        </form>
    {/template} 
    
  3. src\main\resources\xml\article-template.xml: Define the blueprint template for your new page. This file contains static HTML text, and dynamic <at:var> variables.
    1. Define dynamic variables through context.put(myVariable,"blah"); in ContentTemplateContextProvider.java, and then use them here through <at:var at:name="myVariable" /> .
    2. Define static text in the .properties files and use it here through <ac:placeholder><at:i18n at:key="com.my.company.kbarticle.mytemplate.myplaceholder" /></ac:placeholder> .
  4. src\main\java\ — Write your ContextProvider (to define dynamic data for substitution in the article template’s <at:var> elements), write your EventListener (to run Java code after page creation), and write your serialization classes.
    Tip: In the ContextProvider, I changed the declaration to
    public class ContentTemplateContextProvider extends AbstractBlueprintContextProvider.

Sources: simple blueprint plugin, intermediate blueprint plugin, advanced blueprint plugin


Developing Confluence Blueprint Plugins

Posted by admin on April 13th, 2014 filed in Java, Wiki
Comment now »

I’m teaching myself how the write plugins for Atlassian Confluence wikis, specifically, Blueprint plugins. A blueprint plugin adds a custom entry to the Create Page button of your Confluence wiki. You can hook up a custom wizard that lets the user populate some fields that you can access later when you generate the wiki page with your blueprint. In the simplest case, the wizard lets you fill in the page title and, say, some labels. An advanced blueprint and its wizard can have more complex decision points, and it creates a wiki page by populating a custom template.

Getting Started With Blueprint Plugin Development

Atlassian provides a setup tutorial for beginners. Since it left some of my specific questions unanswered, I wrote my own tutorial how to get started with the Atlassian SDK in a previous blog entry. You should read it first.

After installing the SDK, I continued going through the Simple Confluence Blueprint Creation tutorial.

Tip: 
Where the Simple Blueprint tutorial says “time to set up your IDE”, you can either continue with Eclipse as described, or have a look at my Confluence Plugin Development with NetBeans tips.

How to Create a Blueprint Plugin:

Confluence projects are Maven-based, but the Atlassian SDK brings its own (useful!) Maven wrappers for project creation, running, testing, and cleaning.

  1. You create a skeleton project for a Confluence plugin using the atlas-create-confluence-plugin command provided by the Confluence SDK. You provide some properties, such as artifactId which is used as project name (in this example, kbarticle).
    atlas-create-confluence-plugin 
    Confirm properties configuration:
    groupId: com.my.company
    artifactId: kbarticle
    version: 1.0-SNAPSHOT (default)
    package: com.my.company (default)

    You now have a directory named after your $artifactID, here: kbarticle.

  2. Each Confluence plugin is made up of Plugin Modules. Go into the newly created plugin directory named after your $artifactId, and create a module:

    cd kbarticle
    atlas-create-confluence-plugin-module
  3. Now specify module properties interactively. E.g. I chose to create a Blueprint plugin here.
    Select Plugin Module: Blueprint (1)
  4. Define a reader-friendly blueprint name, description, index key, and one template key (I used the default template key).
    Note: By index key, Confluence means the default label for all pages created from this Blueprint! Choose something user-friendly.
  5. I chose to add advanced features to my plugin, they are well described by the wizard. You need these features if you want to run a wizard dialog before plugin creation (dialog-wizard.js), or if you want a context object to access custom variables and provide dynamic text (ContentTemplateContextProvider.java), or if you want to run custom Java code after page creation (BlueprintCreatedListener.java), or if you want to generate special index pages, etc.

Congrats, you have created a skeleton plugin project.

How to Clean, Build, and Run Your Plugin

Next you want to clean, build, and package the skeleton plugin, and install it into a Confluence instance, and test it. The Atlassian SDK (C:\Users\YOURHOME\atlassian-plugin-sdk\bin) provides you with the following development commands. You run these commands in your plugin directory, where the POM.xml file is.

atlas-clean — 
This command simply removes the generated ‘target’ directory so you can start a fresh build. I clean the project after I changed the POM or if I assume that changes to non-Java files were not picked up when I rebuilt the plugin (which happens and is quite annoying).

atlas-package — This command builds your plugin JAR in the ‘target’ directory. If you have installed a confluence instance, uninstall your old plugin, clear the browser cache, and reinstall the newly built plugin to test it. This manual development cycle works, but it is time-consuming and error prone.

atlas-run — 
This approach is the best practice. The command rebuilds the JAR, builds and starts a Confluence instance (!!), and installs your plugin in it. It takes a while to download dependencies, but it’s not slower than installing and running your own instance.

When it’s ready, the command prints server (localhost) and port to the terminal.

[INFO] confluence started successfully in 633s at http://localhost:1990/confluence
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit
[INFO] [talledLocalContainer] INFO: Server startup in ... ms

Open the given Confluence server URL and log on to your temporary wiki instance using default credentials (admin/admin). Use the menus in the top right to open Administration>Add-ons. If you don’t see your plugin, set the filter to list “all addons” and verify that yours is enabled. 
If your plugin is missing or disabled (grayed out) you need to fix an error before it can be used! Search for your plugin name in the terminal output, and interpret the StackTraces.

How to Work Smart using DevTools

After your skeleton plugin works, you want to add features, and test them right away in the browser. Typically, you use atlas-run together with Atlassian’s FastDev. The FastDev Plugin detects shift-reload of wiki pages in your browser, and reloads the underlying plugin. FastDev (as well as your own plugin!) is automatically included when you run atlas-run in your plugin directory. When you use atlas-run, you need to install neither FastDev nor your own plugin manually.

Go back to the Confluence instance running in the browser. Did you note the developer tools in bottom left corner? (They are collapsed by default! Click to unhide them.) Enable the Dev Tools buttons to ‘Rebuild’ and ‘Live Reload’ your plugin.

  1. The first button only reloads the plugin if the last-edited date of a compilable file has changed (typically, that’s a Java file).
  2. The second button claims to be able to reload other files too, but it doesn’t always reload all of them… I assume changes to atlassian-plugin.xml and pom.xml are like open heart surgery, so don’t expect it to do that reliably…?

Being able to reload Java, SOY, and JS files definitely comes in handy during the main phase of development, when you already have the POM and plugin descriptor files down. After a major change, I typically clear the browser cache and press F5 to be sure I’m really testing the latest build. If my changes are not picked up or it gets stuck, I quit the server and re-run everything.

There are some things that I recommend doing first (before you write actual code), such as filling in your name and supplying an icon for the plugin, and getting an overview of what to put where, feel free to continue reading there.