Monday, December 07, 2015

Madcap Flare 11 - HTML5 Output without a Skin? Imposibruu!

If I had a blog dedicated to tech writing, I would definitely post this on it. But since this is my general-purpose-geek-whatever-goes-blog, it comes to reason that "miscelaneous" stuff would come here, right?

In this post I'll take you on a short adventure I've recently had while trying to deeply customize the HTML5 output generated by MadCap Flare 11, after recently upgrading to it from version 7. If you're familiar with Flare, you know that doing Web output can be pretty involved - there are a lot of moving parts, including Master Pages, Skins, Stylesheets and Proxies, to name a few.

Essentially, the goal here is to provide you with a blank canvas where you can customize, almost 100%, the HTML5 output generated by Flare. This can be super useful if you're a) a web designer yourself or b) have a web designer available to do that work for you. And, it becomes almost indispensible if you have a "corporate" style that you want your documentation to be as close to as possible.

There's only 2 things that are really required to make this work as an example. The rest of the "useful" stuff we'll add later:
  1. A Master Page. This is where you'll add your design, around the body proxy.
  2. The Target needs to be in HTML5 and NOT use a skin. 
Sounds simple does it not? Actually, it is, once you've figured out what's necessary - I've done that work for you, you're welcome! Let's dig deeper.

The Master Page

So the Master Page is just HTML code that's inserted around your body text, on each file that's created in your output. We're going to use this to create our "design". Let's start with something really, really basic just to give you a feeling of how "simple" it can be. Create a Master Page by going to the Project Tab, then going into New -> Add Master Page. Give it a name, like, say, "No-skin". (Note: You might already have a "basic" Master Page. If so... skip on to the next section, as the build-in master pages are pretty much built the right way!)

Go to the "Text Editor" view and paste the code provided: Pastebin link

If you've ever worked with HTML you'll recognize just about everything here, with the only exception of the MadCap:bodyProxy element. This is basically the placeholder for the contents of your topic, aka everything in the tag of that topic.

Alright, now this is a very basic Master Page that contains nothing in terms of navigation, but we can add that in a second. Let's move on to the next step.

An HTML5 Target that doesn't use any skins

So now we get to the interesting part: building the target. Go to Project -> New -> Add Target. Make sure the Output Type is set to HTML5, give it a name (my-user-guide, or whatever) and click Add.

In the properties, the following things need to be change:
  • In General, ensure that the Master TOC and Master Stylesheet have been attributed values.
  • In Skin, use the drop-down to change "Skin" to "(none)".
  • I Advanced, go to Master Page and change it to Resources/MasterPages/No-Skin (or whatever you named it).
  • If you want to change other options like conditions and variables, go ahead. 
And now the fun part. Save this target, and hit Build. After the build is done, click on View and open it in your favorite browser. Should look something like this:

Adding navigation and other proxies

So the above preview looks really dull, right? Of course it does, because there's no navigation, no toolbar... Only the header (I added to my master page as above), and the contents of one topic. 

Now what we can do is start adding proxies into the Master Page, to start giving us some useful stuff to work with! In the XML Editor view of the Master Page, you can insert the following proxies:
  • The Breadcrumbs proxy (You are here!)
  • The Topic Toolbar proxy (which shows links such as highlighting, print and such)
  • The Search Bar proxy which adds the search box and button
  • The Menu proxy, which is used to display the Table of Contents. When adding the TOC, to start with I suggest unchecking Context sensitive and changing Levels to Show to (all). You can customize it later on. 
Alright... now we're talking! Check this out:

So everything we really need is here - we just need to style it properly! Obviously, this is where the expertise of a web developper normally comes in. But I'm a great gal so I'll provide you with a complete project at the end of this post. In the meantime, here's what it looks like with a bit of HTML tweaking and some CSS styles:

Ok so in this case I'm reproducing more or less the "typical" webhelp tripane design. But it doesn't need to be this way. You could place the TOC on the right in a floating sidebar, you could have the TOC drop-down from the left or right or have it fly around avoiding the user's cursor... whatever, basically. My point here is that the sky's the limit and your web developers will be happy to know that they can tweak this to the point where it will look like what you want, from top to bottom, start to finish. And, by the way, you can add conditions, variables and anything else in the Master Page that you would in a normal topic. So that's awesome too.

Custom Search Results Page

One issue I came up with later in my design is that the Search Results page wasn't using the Master Page, and I wasn't sure how to proceed. Some help from the Madcap forums later, the solution came about: Create a new topic inside the Resources/MasterPages folder of your project (I called it "searchresults.html", the name doesn't matter), and simply add the Search Results Proxy inside of this topic: double-click on it, remove all the contents then go to Insert -> Proxy -> Search Results Proxy. I believe it's a workaround for a bug (as this writing, in Flare 11). But that topic in a custom location is all that's necessary, thankfully.

Need more help?

Post on the Madcap Flare forums, or comment below!

Wednesday, November 16, 2011

Jean Quan and Michael Bloomberg are the reason I support the Occupy Wall Street movement.

When I first started to hear about the Occupy Wall Street movement, I was very ambivalent about it. I wasn't quite sure exactly what it was about and, though I had a vague feeling that their demands were right and that the whole idea was good, I saw diverging views that lead me to believe it wasn't serious. First, they were often portrayed as a bunch of snobby pricks that weren't part of the working class but still had enough money to camp out in a park, with their cell phones and computers, and nothing would come of it. Another argued that the movement didn't even understand what they were themselves - that they were claiming Socialism was better, but at the same time were refusing to serve food and give shelter to the homeless.

But it's too easy to simply dismiss a whole movement from the comments of a few detractors. I started following @OccupyWallStNYC and saw another side of the conflict that started to change my views and open my mind to the idea that they were right...

And then, Jean Quan gave the order to the Oakland PD to remove the @OccupyOakland people that were, as usual, peacefully occupying the park (albeit against city regulations). But according to anyone who actually saw footage from that night, including me, the level of force that was used was excessive. Rubber bullets, tear gas, pepper spray, flash bangs, LRAD (google it), all in very pretty riot gear. They dragged people out of the park when they resisted, completely destroyed (as in tore down and broke) tents and equipment that was there. All this for what reason? For "sanitation, security and fire hazards".

Regardless of your political views, if you believe that sending hundreds of SWAT uniforms with a full complement on non-lethal weaponry against a group of peaceful protesters sitting around in a park and camping there is the proper decision, I probably don't know you and I want no part of your entourage. But Quan attacking OccupyOakland was not the first of such acts, and especially not the last.

Two days ago, in the middle of the night (2AM local time to be precise), NYPD SWAT teams (along with the Counter-Terrorism Unit) started surrounding Zuccotti Park, birthplace of the #OWS movement and occupied for just under two months. Then, they proceeded to remove anyone in the vicinity that was part of the press. That's right, the NYPD shut off the media from witnessing the event. Rosie Gray, reporter with The Village Voice, told an office "I'm Press!" and was answered "Not tonight, you're not".

Once that was done, the raid began. Again, people were dragged away, property was destroyed, 5000 books in the Occupy Library were thrown into a container along with the possessions of anyone who had decided not to leave the park when NYPD started handing out pamphlets telling them to leave the park, and loudspeakers blasting the same thing (again, at 2AM). Those who were not arrested remained, dazed but still strong, around the park where the NYPD setup a security perimeter to throw out the rest of the "trash" remaining in the park.

Now, I'm not an expert in politics and world news, but this is never something that I would expect to see in a country such as America (or Canada for that matter). It shows us a couple of very important things.

First, the 1% is bothered, if not scared. Honestly, Zuccotti park is in the middle of the Business area in New York. There are no residents around the park that could have possibly been annoyed by the occupation. On the other hand, considering the growth of the moment and the attention it is slowly building, people that are directly targetted by the movement are probably starting to feel the pressure.

Second, the movement is already treated as a revolution. Why else would SWAT teams and riot gear be needed to remove peaceful protesters from a park? These city mayors are being pressured (Bloomberg's speech on "this was my decision alone" only serve to reinforce this theory) to try to "quell the rebellion" before it gets too big and explodes in their faces.

Third, protesting isn't a freedom anymore. It's easy for the people in power to let the "lowly peasants" do a little picketing for half a day and maybe block a street with their presence and their signs, get their media coverage and then dissipate. This is "how it's done", and it achieves nothing. But actually putting the pressure in the right place, occupying a public park to raise awareness of an issue that affects every aspect of our "civilized" society today, is clearly not an easy task. Ask the ones that have been thrown in jail for just being there, ask the media who have been taken away so they couldn't cover an important media event for the people, and ask the people of which the camps have been raided, their possessions removed, and nowhere to sleep.

So in conclusion, thank you very much, Quan, Bloomberg and all the others that are attacking the movement. Your actions have shown us just how weak you are, how scared you have become, and how true our movement is.

Let's get this revolution started, shall we?

Wednesday, November 02, 2011

My hate of Internet Explorer knows no bounds

I`m not the only one that has issues with Internet Explorer. Any web designer will tell you that IE sucks. It's to browsers as French is to languages: bloated, complex, and enough exceptions to fill a book.

But in the last 3 days, I've been fixing one problem after another, because different versions of IE have different quirks - but in general, every one of them is a bitch to troubleshoot when you don't know exactly what you're dealing with.

On Monday, I spend hours tracing down an issue that was making IE8 crash its tab when I opened the online html documentation I'm maintaining. Every single other browser (and every other version of IE) worked perfectly well, no error messages, no warnings. But IE8 was being a dumbass and quitting for no apparent reason. After screwing around in the javascript, the frames, the HTML, I chanced upon the fact of removing my jquery import and my javascript code in general, and suddenly it worked... A google search revealed that, specifically, [ IE8 + jQuery 1.6.2 + CSS background: url(something); + a page refresh ]  caused the crash, because a single line of code that "fixed" an IE8 bug related to CSS backgrounds was removed in error. The solution was to update jQuery to the latest version, 1.6.4, which restored their workaround to the bug. IE8 = bitch.

On Tuesday, a colleague of mine reported that IE7 was freezing and taking 100% CPU on one core. Again, Firefox, Chrome and every other version of IE had no issues at all. Why was this happening? Well, I recently added tiny bit of code that detected when the browser window was resized, and re-centered buttons on the screen (absolute positionning being a bitch of its own). In IE7 specifically, whenever an element changes on the page, it triggers the resize event. So, it was running into an infinite loop where it would resize, re-center, trigger a resize, and start all over again. To fix this, I had to add a small jquery plugin called "smartresize" which "debounced" the refresh function with a timeout. IE7 = bitch.

And today, another issue reared its ugly head: In IE9, a client would click on a "Send Feedback" link I provide, enter his name, email and a message, click on Submit... And the dialog would just stupidly sit there. And again, every other browser and version of IE I tested worked perfectly well, no issue whatsoever. The cause? I was sending an AJAX request through POST and receiving a JSON response. Now, something in IE9 (still not sure what) bugs out, thinks it should be receiving XML, sees JSON, and thinks "oh this is a mistake". Instead of triggering the jquery success: function, it triggers error:. Because I had already spend half my week fixing IE's stupidities, I resorted to a dumb workaround just to get rid of it: I put the contents of my success: function in my error: function (which is never triggered and didn't even exist before now anyway). IE9 = bitch.

Now, if you're a web designer you may think part of this is my fault - not testing properly in all versions, not knowing the quirks by heart, lacking troubleshooting abilities. But in all honesty, if I didn't have to support IE (if 40% of our users weren't on IE8), I would have spent the last 3 days doing more constructive things like, I don't know, updating our software documentation or writing FAQs.

Question to you: how many of your head banging sessions were caused specifically by Internet Explorer?

Tuesday, May 24, 2011

Transparent PHP proxy with GET, POST and HEADER support.

I needed to do cross-domain AJAX calls from a jQuery front-end to a PHP backend which was on another domain, and couldn't find a complete, functional example online... so I created my own. Since both servers had PHP (but the backend needed extra stuff that wasn't on the frontend server), doing a PHP Proxy was a great idea.

What this proxy supports:
  • GET and POST requests (POST was the whole reason for this, since jsonp doesn't support it!)
  • HTTP_REFERER check (only accept requests from one server)
  • COOKIES, in both directions (setting from the backend and sending from the frontend)
  • HEADERS, all of them, in both directions. This means it's a transparent proxy (yay!)
What it doesn't support (yet, maybe):
  • Dynamic destination (though that's relatively trivial to change), because I don't need it.
  • Load Balancing/Cycling, I may add this as a personal exercise in the future.
  • Authentication, beyond the referer check, or session (this should be handled by the backend anyway)
The Code

Because sucks with code, the code is available directly on Google Code, at the following URL:

Tuesday, May 10, 2011

The Forward Time Travel Paradox (FTTP)

Time to go into a little bit of metaphysical thinking here, thinking about paradoxes and time travel. If I'm going to post only once every blue moon, may as well make it an interesting one, don't you think?

So I am going to put forth a small hypothesis: If you were to travel into the future, the future you would travel to could not, ever, be the one that would happen when you get to it "the slow way". I shall call this hypothesis (or is it a theory? I don't know) The Forward Time Travel Paradox.

Every single science-fiction story that I've seen up to now that deals with time travel in a semi-logical way tries to cover the area of time paradoxes. They say, if you go into the past and kill your grandfather, or change anything that could make yourself not come into existence... Then you cause a paradox that destroys spacetime. But none - not a single one - talks about the paradox of travelling into the future. They all go "oh cool, the future, now we know what's going to happen, cool!" and go on with their story. Let's challenge the status quo.

The Premise

Let's say I invent a time machine that can go into the future. I want to test it for the first time (I know it works, I`ve done the calculations) so I simply hop in, set the dial for 100 years (so as to not run into my future self, obviously) and push the button. WHAM, I'm now in 2111.

If this happened to me, the first thing I would do would be to find any sort of data connection (probably some sort of wireless protocol with a TB/sec connection speed) and Google myself... And what would I find? Certainly not  front page news or a peer-reviewed paper on folding space into a wormhole to travel into the future... At best, some clipping on page 95B about my mysterious disappearance, and my last blog post before I left... My Gmail with a few million emails (and about a googabyte of free space!). What happened... to me? My life's work, gone? My hole existence, wiped out?

So I try to come back, expecting the worse... But nope, here I am back in the "present" and everything seems to go as planned! I publish my research paper, become famous, become known as the inventor of the Time Machine(tm). But one thing nags at me and becomes obvious each time someone visits the future, even by just a few days: It's never exactly the same when you actually get to it in "normal" time. There are always details that have changed!

The Explanation

The explanation is quite simple really; every time you hop on to the future, you're creating an alternate timeline in which you disappear and only re-appear at your destination. You travel 100 years into the future, it's a timeline where you were gone for that 100 years. But when you travel back, because you re-appeared before that 100 years, you've basically changed the future... You've just destroyed the timeline you created when you first went forward.

That would happen every time someone went forward into the future. All their possible children and descendants, every action they were to do, would temporarily go away until they come back even, if just for a millisecond. So what can be done about that? Absolutely nothing. Were we to actually figure out a way to go into the future, there would be no way of knowing whether or not the one we visit would be the one that would happen!

And, of course, an extra layer needs to be added to this basic truth, for any and all who still doubt. In the same way that visiting the past would change the present, visiting the future would also change it. If I were to visit a future where I could see the loto numbers, come back into the present and win a couple of million dollars... Then the future that I visited would no longer exist... Or rather, according to some theories, I would have created a new timeline where I won the lottery, a new branch in the eternal tree of spacetime, and I would follow this new path.


Time is fluid and ever changing. We may be part of a timeline where time travel will never be discovered, or it may be discovered today. Or, someone from the future may appear tomorrow and simply give us the technology just because they can, thus creating a new timeline where humanity starts using time travel in 2011 instead of 2273! Would we go back even further in time and give it to ourselves 100 years ago? Who knows... Once thing's for certain - when it comes to time travel, there is no such thing as a straight line and no such thing as just a visitor. As with Quantum Physics, the simple act of observing the future (or being observed in the past) changes the whole outcome of the experiment.

But then again, I don't understand Quantum Physics. If I were to understand quantum physics, I don't believe I would really understand it (or so the saying goes...).

Cheers for now, see you in an undetermined amount of time!