Public vs privileged webhelp build

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
Simon Dismore
Posts: 454
Joined: Thu Nov 16, 2006 1:29 pm
Location: London, UK

Public vs privileged webhelp build

Unread post by Simon Dismore »

I'm trying to find the best way to build two versions of webhelp so that one is locked for more privileged users, the other for less. The idea is to use a publishing task that generates the two versions in sync, and locates the privileged one on a server that requires authentication. The locking might be for draft vs final, user vs superuser, free vs subscription etc.

The challenge is that both versions should contain all the topics, but in the less privileged version some topics have their <%TOPIC_TEXT%> replaced with a placeholder asking the user to log in, which transfers them to the privileged version. The benefits are:
  • no need to maintain conditional logic within topics to prevent broken links,
  • readers can see TOC entries for locked content, so they have an incentive to log in or register etc.
What's the best way to achieve this? I know it can be done using IF/ELSE conditions within topics, as below:
conditions-within-topic.png
In that screenshot, the topic text is displayed in both builds and the login placeholder doesn't appear in either build. To force login for a particular topic, I just remove the "PUBLIC BUILD" term in the condition, so the content is included when I build the privileged version, but the placeholder when I build the public one. The placeholder can be a snippet so there's only one place to maintain it.

This technique works but it feels hack-y:
  • The conditional tags mess up the clean look of the editor and are easy to over-write by mistake.
  • There's no flexibility to have multiple TOCs with different locking conditions.
  • I'd like the locking decision to be visible in the TOC, as below.
custom-build-ID-in-editor-toc.png
I'd rather do this using build conditions in the HTML template to replace the <%TOPIC_TEXT%> with a placeholder. I've read conditional output in HTML templates but I can't see how that can do the job. Any suggestions?
You do not have the required permissions to view the files attached to this post.
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Public vs privileged webhelp build

Unread post by Tim Green »

Hi Simon,

If you really want to replace the entire topic content generated by <%TOPIC_TEXT%> the easiest way to do this would be to create a skin in which you replace the <%TOPIC_TEXT%> variable with your own HTML code. You will get a warning telling you that the template is missing the variable, but it will still compile. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Public vs privileged webhelp build

Unread post by Tim Green »

Simon,

An even more elegant solution is to enclose the <%TOPIC_TEXT%> variable in your skin in a build condition, then you can do everything with a single skin. It has the added benefit that Help & Manual's parser doesn't notice that the variable is in a condition, so it doesn't complain at all that it's not there. This means that you won't get any spurious warnings in your exit conditions if you're publishing with a batch as part of a build process.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Simon Dismore
Posts: 454
Joined: Thu Nov 16, 2006 1:29 pm
Location: London, UK

Re: Public vs privileged webhelp build

Unread post by Simon Dismore »

Tim Green wrote:Simon,
An even more elegant solution is to enclose the <%TOPIC_TEXT%> variable in your skin in a build condition, then you can do everything with a single skin.
That's what I've been trying to do with build IDs, along the lines of...

Code: Select all

<IF_PRIVILEGED_BUILD|UNLOCKED><%TOPIC_TEXT%></IF_PRIVILEGED_BUILD|UNLOCKED>
<IFNOT_PRIVILEGED_BUILD><IFNOT_UNLOCKED>Please <a href="<%SECURE_BASE%>/<%TOPICID%>.html">log in</a> to view this topic.</IFNOT_UNLOCKED></IFNOT_PRIVILEGED_BUILD>
My idea was that PRIVILEGED_BUILD would be a "true" build ID that I toggle in the publishing task, whereas UNLOCKED would be a build ID that I'd attach to individual topics to mark them. That doesn't work though, does it?

I suppose I need either (a) the ability to use topic text variables with IF/IFNOT, or (b) new conditional operators like IFDEF and IFNDEF that work with build IDs at the topic level, e.g.:

Code: Select all

<IF_PRIVILEGED_BUILD><%TOPIC_TEXT%></IF_PRIVILEGED_BUILD>
<IFNOT_PRIVILEGED_BUILD><IFDEF_UNLOCKED><%TOPIC_TEXT%></IFDEF_UNLOCKED>
<IFNDEF_UNLOCKED>Please <a href="<%SECURE_BASE%>/<%TOPICID%>.html">log in</a> to view this topic.</IFNDEF_UNLOCKED></IFNOT_PRIVILEGED_BUILD>
Approach (b) fits more naturally into the build model, allows multiple TOCs, and having the custom build ID displayed in the editor's TOC would be a big plus. I might write it up as a wishlist item for 2018...
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Public vs privileged webhelp build

Unread post by Tim Green »

Hi Simon,
My idea was that PRIVILEGED_BUILD would be a "true" build ID that I toggle in the publishing task, whereas UNLOCKED would be a build ID that I'd attach to individual topics to mark them. That doesn't work though, does it?
No, because build options are always global. They exist throughout a project; you can't have them exist in some topics and not in others.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Simon Dismore
Posts: 454
Joined: Thu Nov 16, 2006 1:29 pm
Location: London, UK

Re: Public vs privileged webhelp build

Unread post by Simon Dismore »

OK, I've written this up for the Wish List: New feature for IF/IFNOT in HTML templates.

Thanks as always for your patient feedback 8)
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Public vs privileged webhelp build

Unread post by Martin Wynne »

Hi Simon,

Don't forget that in H&M you can choose the option to create .php files instead of .htm or .html (in the HTML Export Options).

You can then use a page template, or insert an HTML Code Object, to create whatever PHP code you want. This could deliver a normal page, or a secure page, or redirect to a login page, etc.

PHP code runs on the server, not at the client end. You wouldn't need to create different versions or builds of your Webhelp.

Ditto for .asp files if you are running on a Windows server.

regards,

Martin.
Simon Dismore
Posts: 454
Joined: Thu Nov 16, 2006 1:29 pm
Location: London, UK

Re: Public vs privileged webhelp build

Unread post by Simon Dismore »

Hi Martin, that's a good point, thanks.

I'm aiming for a "devops" model where no further human intervention is needed. So I need an automatic way to tell the server which topics are public vs private. This info is in the source table_of_contents.xml file so I suppose the publishing task would include a step to parse the XML into a form the server could read.

My original assumption was that I was using static web servers. If I'm being forced to execute logic on the server then I'll probably be more radical, e.g. publish everything to JSON – Tim's PP3 jstopic files are 99% of the way there already – and store in a NoSQL database. That would enable a lot of interesting scenarios....
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Public vs privileged webhelp build

Unread post by Martin Wynne »

Simon Dismore wrote:I'm aiming for a "devops" model where no further human intervention is needed. So I need an automatic way to tell the server which topics are public vs private
Hi Simon,

For that you would just select the appropriate page template for the topic. Secure topics would contain something like this in the page template:

Code: Select all

if(!is_user_logged_in())
{
header( 'Location: '. HTTP . SERVER_NAME . BASE_DIR . '/login.php' ) ;
}
Which would re-direct to the login page instead of displaying the topic, if the user has not logged in.

If you are on a Linux server, PHP support is almost universal nowadays.

regards,

Martin.
Simon Dismore
Posts: 454
Joined: Thu Nov 16, 2006 1:29 pm
Location: London, UK

Re: Public vs privileged webhelp build

Unread post by Simon Dismore »

That's good advice. Thanks again!
Post Reply