Dynamic snippets? Snippet as template?

Please post all questions on Help+Manual 8 here

Moderators: Alexander Halser, Tim Green

Post Reply
Tony Starbuck
Posts: 12
Joined: Thu Feb 21, 2019 6:17 pm

Dynamic snippets? Snippet as template?

Unread post by Tony Starbuck » Tue May 19, 2020 4:49 pm

I've been through the forum and have found similar threads but they're all old.

I'm hoping to create a snippet that functions as a template, where text in the topic fills the gaps. Examples:
Download the %version version from %here.

The black bold text would be static while the dynamic %text would need to be replaced in the topic editor.
The snippet could later be modified to
The %version version can be downloaded %here.
With a single edit on the snippet, all topics would get the new static text without disturbing the dynamic text in each topic.

If I could ensure that a snippet is not wrapped at build time with markup, I could do something like this:

Code: Select all

<para><snippet src="file::text1.xml" inline="true"/>text1<snippet src="file::text2.xml" inline="true"/>text2<snippet src="file::text3.xml" inline="true"/></para>
So the three snippets can be changed, knowing that they will be rendered in order at build time. The problem there is that I did try to reduce the markup in one of those snippets, and on Save the markup was refreshed with a para tag and style. That also requires three snippet insertions per phrase, which is a pain.

I've read threads about dynamic text, user-defined variables, dynamic content generation with external code, etc. I can use whatever best practice is currently recommended - I just don't know what that is now.

BTW, we're running 8.0.0.5452

Thanks!

User avatar
Tim Green
Site Admin
Posts: 21740
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Dynamic snippets? Snippet as template?

Unread post by Tim Green » Tue May 19, 2020 6:45 pm

Hi Tony,
BTW, we're running 8.0.0.5452
Not relevant for your question but you're way out of date and still have a lot of early bugs. The current build is 8.0.3 Build 5500. Please update asap:

https://www.helpandmanual.com/downloads.html?upd

Anything you edit in the XML will be thrown away silently if it doesn't conform exactly to the HM XML schema, which is documented in the Helpman_XML_ref.chm file, which you can find in the Help & Manual program directory. However, that won't really help you here because linked snippets don't work the way you are describing here. A snippet is an entire contiguous file and its reference in the topic editor is just that -- a reference to a full file. A linked snippet is shown in the topic editor, but that is just a preview. It's not editable. On publishing the current version of the referenced file is rendered and inserted in the output and becomes part of the output.

What you are thinking of here is something that combines the editable nature of a copy & pasted snippet with the live updating of a linked snippet, and that isn't available. You could use a copy & paste snippet like this but only once. As soon as it's pasted it becomes normal text with no reference to the source.
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.

Nadia Gaganova
Posts: 53
Joined: Thu Sep 24, 2015 11:57 am
Location: Moscow

Re: Dynamic snippets? Snippet as template?

Unread post by Nadia Gaganova » Wed Jun 17, 2020 10:17 am

Hi Tony,
just in case you haven't found your best solution yet. We are using variables in a similar context: the snippet contains <%TEXT%> and the topics each define the value of the TEXT variable. I don't think it would be maintainable with hundreds of topics, but works nicely with a couple of dozen.
Omit needles swords

Tony Starbuck
Posts: 12
Joined: Thu Feb 21, 2019 6:17 pm

Re: Dynamic snippets? Snippet as template?

Unread post by Tony Starbuck » Sat Jun 27, 2020 9:12 pm

@Nadia - thank you for your kind suggestion. I will look at this.

@Tim - We are now running v8.0.1.5536. Thanks.

I understand that the product does not do what I suggest. I've been looking at the wealth of documentation for text and HTML variables. Perhaps this usage with snippets can be accepted as an enhancement request?

Actually, based on Nadia's comment this might already be done. In my example:
Change from my original thought: The %version version can be downloaded %here.
To: The <%VERSION%> version can be downloaded <%DOWNLOADLINK%>.

Nadia's example is with per-topic variables but this looks like it would work well globally.
If we can't use snippets for this, an alternative might be nested text variables. For example, the above text can itself be set into a variable which is then embedded in topics as <%DOWNLOADVERSION%>. This is not as nice as snippets, however, which render in edit mode, compared to variables which do not render in edit mode.

User avatar
Martin Wynne
Posts: 2615
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Dynamic snippets? Snippet as template?

Unread post by Martin Wynne » Sun Jun 28, 2020 3:46 pm

Hi Tony,

What is your output format? If HTML-based, you might like to consider using #MERGE in an HTML Code Object for such variables.

The merged file can be a plain .txt file, and if included in your Baggage files it can be edited directly in H&M*. It need contain only one word if that is all you want.

Code: Select all

#MERGE Baggage\abc_123.txt
This is much more flexible than the built-in variables, because the merged file can contain anything you like, including HTML formatting, variable tables, variable images, etc. But it's no good for PDF or Word or Print output.

*If you edit the Baggage file in H&M, you must remember to save your project before publishing, otherwise the changes won't be reflected in the output. Also of course, as a Baggage file it will be uploaded needlessly to your server. The alternative is to create a separate sub-folder in your project for such files, and edit them in Notepad++.

cheers,

Martin.

Post Reply