variable information in a snippet

[kmaddox1]

I'm not sure I fully "get" the concept behind the new snippet functionality in RH7. I understand the part about how they are reusable blocks of text that you can create once and insert in many places. That makes sense, but I rarely include *exactly* the same block of text in multiple places. What I do, though, is to include very similar instructions in many places. The steps vary slightly depending on the topic. That is, the topic called "Creating X" includes numbered steps for setting up X; the topic called "Creating Y" includes numbered steps for setting up Y; and the topic called "Creating Z" includes numbered steps for setting up Z. Except for the names of what's being created (X vs Y vs Z), the step-by-step instructions are the same.

I was hoping to use a snippet for the text in topics X, Y, Z that is identical (most of it), while somehow inserting a variable in the snippet that would change from X to Y to Z, depending on the topic. Can that be done?

[Captiv8r]

Hi Kathy

Seems to allow adding a User Defined Variable in a snippet with no issues. Just edit the snippet, then create or assign the User Defined Variable where you want.

Cheers... Rick

[kmaddox1]

Thanks, Rick. Yes, I can insert a user-defined variable in a snippet, which works fine. So I guess my question really has to do with the use of user-defined variables. Specifically, how do I change the definition of a variable used in a snippet, based on where the snippet is used?

For example, I created a variable called "parameter" and used it a several places in my "General instructions for parameters" snippet. I then defined this variable to mean "Auto Search," which works great for the topic that provides instructions for creating a parameter called Auto Search. But I also want to use the same snippet in another topic that provides instructions for creating a parameter called Relationship. That is, I want my "parameter" variable to mean either "Relationship" or "Auto Search" (or other things), depending on which topic the snippet is used in. The instructions in RH aren't clear on how (or if) you can do that.

[Peter Grainge]

A snippet has to be the same in all topics. It follows therefore that the variable can only have one value.

[kmaddox1]

Thanks, Peter. That's what was slowly dawning on me. Unfortunately that makes snippets a lot less useful than I'd like (since I almost never use *exactly* the same block of text in multiple places). Instead, I very, very consistently use the same basic structure in many places, varying only a keyword word or two between topics). I'd like to request that Adobe look into supporting this functionality for the next release. What's the process for doing that?

[Peter Grainge]

http://www.adobe.com/cfusion/mmform/index.cfm?name=wishform

is the answer to your question but I don't see how what you want can be done.

Once the content of a snippet, be it part of the text or a variable, is different, then you are not using the same snippet.

[MergeThis]

Why can't your snippet contain conditional tags? Have you tried that? I'm still on RH X502, so I can't test it myself.


Good luck,
Leon

[Peter Grainge]

Leon

The snippet would contain Value 1 and Value 2, both with different conditions. I think that is what you are suggesting in the way that before variables you would then create a build expression that used one of those values.

You can apply a tag to the snippet but come build time you would get just one of those values from the snippet and that would then cascade into all the topics. Think of the snippet as a topic, the content is either in or out. You cannot create a build expression that looks at where the snippet is being used.

The whole idea of snippets is "this is what I want **everywhere** it is used, not "sometimes I want this and sometimes I want that". That is two snippets. Somewhere the snippets, or the variables within, or the tags within, would need to be mapped to topics so that RH would know where to apply the differences.

[Captiv8r]

Hi all

I think if Adobe were to change the way snippets worked, it could be made to happen as Kathy wants. As I see it, she is wanting *Most* of a snippet to remain the same and some variable text here and there. That much can clearly be accomplished today using a combination of multiple snippets with multiple variables. She would have to duplicate a particular snippet and add variables as required.

Here comes the kicker. If I'm understanding correctly, she would love to see the ability to have something along the lines of a "Master" snippet. So you would define the master with the boilerplate text. Then create duplicates based off the master. Insert either static text or a variable for the "different" information. (I'm not seeing why a variable would really help here). Because these "other" types of snippets are based on the master, all you would need to do is to change the master verbiage to update any copies based off it. So in this fictitious world where everything would be ponies that ate nothing but rainbows and pooped butterflies, this would provide exactly what was needed, no?

For what it's worth, I think some of what Peter covers in Terminology on his site may assist in this case.

Just thinking out loud... Rick

[Peter Grainge]

Don't we have enough trouble with cascading style sheet, embedded style sheet and inline style conflicts? Snippets within snippets looks like it has the same potential! :-)

[Captiv8r]

ROTFLMAO!!!!

Hmmm, snippet within a snippet. Don't think I've tried that one. I wonder if it would work... Hmmmm Must.... fight.... resist... urge.... to... play.... wife.... calling... meet for.... coffee... aaaaaaargggghhhhh!

No, I was thinking of a LOTR snippet. Maybe we call them Gollum's. One snippet to rule them all. Bwa ha ha ha haaaaa

[Pet3689]

I would be a step in the right direction, and perhaps be useful by itself, it a topic could have topic-specific variables.

I am thinking about a hybrid "Title" (or "File Name") variable and a user-defined variable.

For example, for Topic "Set-up Product A", I would have a variable "Name" = "Product A". And similar for Product B, etc. I could then add the variable "Name" to the text in that topic (and it would be undefined anywhere else).

Now, if Snippets were made to be a bit less "static", i.e., you could add the topic-specific variables (currently "Title", "File Name") to it, you would have an extremely powerful tool.

It does not sounds like either suggestion is difficult to implement, and their combination will make many users happy, I would like to believe.

[MergeThis]

Could you find a JavaScript expert, somewhere in your organization, to create some type of document.write scripting based on slicing (or whatever they call it) a variable from the TITLE or H1 string?

That seems like the only hands-off method that would accomplish what you want (since Peter stomped on my conditional-tag idea).


Good luck,
Leon

[kmaddox1]

Cool. Glad to see that my bewilderment has created some discussion. What I'm envisioning is something like a master snippet used in a mail-merge function kind of a way for repetitive (but not exactly duplicate) text. Here's how it would work:

You create the master document/snippet and hard-code whatever text is static (eg. "To create a new ____, follow these steps: 1) Click File > New. 2) In the Name field, enter the name of the _____ you are creating....").

The underscores in the snippet represent fields that can have different meanings depending on where they are used. For example, in one topic, the underscores would be defined to mean (in my case), "Auto Search"; in another, they would be defined to mean "Relationship." When you added the snippet to the topic, you would get to define the meanings of the variables used in that snippet.

It would really be no different than using mail merge in Word--you create a master letter and combine it with values you defined elsewhere. Voila! All of at once, a whole bunch of closely related, but not quite identical instructions are generated. Think of how cool that kind of functionality would be for localizing lots and lots of instructions, keeping things consistent.

[Peter Grainge]

To make mail merge work, Word requires a database or a reference source which brings us back to having to indicate somewhere what goes in what topic.

I have to go out now but I prepared the following failing to pick up on the mail merge point, hence it not being covered in what follows. See what I have said and post back. I won't be able to respond today though.

*************************************

Kathy

Read this through before reacting as I am on your side, although it may not appear so at first. :-)

How would you envisage telling RH "In this topic I have included Snippet X and within that there is a marker, in this topic the value of that marker is Red". Then in another topic you have to tell RH that you want the same snippet but the value of the marker is Green? Something about that snippet has to be different or the way it is added has to be different. How do you envisage you would do that?

Even taking the idea of a master and child I am finding it difficult to define that logically and unless it can be defined logically, it cannot be programmed. Let's say the master is "I have a rabbit" and you want snippets to be able to include "red" or "green" to give you "I have a red rabbit" or "I have a green rabbit".

- If we say that there is a marker in front of "rabbit" then that is no different to a variable. We are then back to how do you tell RH what value you want for that variable?

- If snippets within snippets were allowed, how would you write the snippet? It is interrupted by another snippet. "I have a [insert some other snippet] rabbit" You would need a snippet for red and a snippet for green. Whenever you insert the master, something would have to tell RH that for that topic either the red snippet or the green snippet has to be specified. I can envisage a programmer being able to write code that recognises there is a snippet within the snippet and popping up a "tell me which one" dialogue. At least though when the rabbit dies, you can get a dog and change the first snippet and in each topic RH knows which inner snippet is required! For now we will rule out further levels of snippets within snippets. So perhaps this route could be programmed but would that really suit?

You are probably thinking why is Peter arguing against me when what I want is a real world need. I agree with what you want as I can see cases where instructional steps only vary by a few words. I am not arguing against you but trying to get out of this debate a specification that can be programmed. What I am doing is playing devil's advocate to draw out that specification. I can see what you want and agree it is a good idea. Other than as above, I cannot see how to specify a programmable solution that has benefits over just writing two snippets.

If you can specify something that would work and has benefits over writing two snippets, then the idea can be put to Adobe and I know that improving snippets is on the agenda. So, I am with you but need you to indicate if what I have suggested would suit, whether you think it has enough benefits to justify the programming (bear in mind it could be at the expense of something more useful as like any upgrade only so many man hours can go into an upgrade) or whether you can see a better solution.

[Captiv8r]

Hi all

Tossing kerosene onto the blaze I am.

Actually, I am finding this discussion fascinating. I think what is at hand here is how snippets are currently handled and a proposed change to that handling. I also believe that several of us have also had a discussion very similar to this one in person.

Currently snippets are a "Block level" item. This means that they absolutely MUST exist on a line all their own. What would be handy in this case is to be able to define them so they would work at the character level. If this were possible, we could have multiple snippets that could maybe be strung together to create a "super snippet" or whatever.

Again, simply pondering out loud... Rick

[Guest]

Fantastic idea, Rick.
That would do wonders for my help system.

During the beta phase I had hoped for user-defined variables which supported HTML.
Your proposal is exactly what I was looking for, though it would still be nice to be able to define UDVs in html, too.

[kmaddox1]

Dear me. I didn't think I was asking for anything so hard! And rest assured, Peter, I do believe you're on my side, since you've been the strongest ally of all of making me productive in RH.

I'm not a developer and certainly don't understand the inner workings of RH. I really don't have a clue how or if this could be done programmatically. I guess I was (naively) thinking that the variable definitions would be stored somewhere in the header code for the topic. When a call to a snippet was made, the definitions from the topic header would automagically be inserted whereever the variable fields appeared in the snippet. That is, the work would all get done when the snippet was added to the topic, not within the snippet itself, which would just be a "dumb" repository for the variable names.

I was hoping it would be somewhat akin to applying different templates or style sheets to different topics--that is, if I use the Red style sheet, then my text styled as "Color" comes out as Red; if I use my Green style sheet, my text styled as "Color" comes out as Green. If all that can happen at the topic level, why can't variables have different meanings for each topic? I.e. the problem isn't so much snippets as variables).

[Captiv8r]

Hi Kathy

Hmmm, your idea seems to work. This would mean that you would have to be willing to settle for odd names for the topics. I just tried editing a snippet. In the middle of the snippet text, I clicked Insert > Fields and Variables... and selected the Title variable. This places the Topic title in there. When I inserted the snippet into a topic, the Title was pulled right in.

Might be worth trying... Rick

[kmaddox1]

Thanks, Rick, I think that will work in my case since my file/topic names are the same as the parameter I'm describing (vs my TOC titles, which are the more user friendly "Creating an X"). But I still think that there should be a way to have variables mean different things depending on the topic they are used in. Just as when I apply a style to a paragraph in a snippet, I could then add variables to each snippet that would only be populated when the snippet was added to the topic.

Have a great weekend.

[Peter Grainge]

So now we have a workable specification of what is needed, I think.

****************************************

If a variable is used in a snippet, it will have the same value in all topics in the output. The value will be the default for the variable or whatever is defined for that output.

There are cases where the variable needs to have a different value according to the topic in which the snippet is used. For example the snippet could be a set of steps where just the name of a button changes.

A solution has been identified but it requires that the topic title is used and inserted into the snippet as a Field Variable. That has shortcomings in that it requires "odd" titles and the snippet cannot be used more than once in any topic with different values.

What is needed is the ability to include in a snippet the name of a hybrid variable, for now let's call it InstanceVariable. Wherever a snippet is included in a topic and that snippet includes an InstanceVariable, RH should prompt for the variable value to be used.

****************************************

Any flaws in that?

[Peter Grainge]

Yes there were some flaws! Try this specification.

****************************************

If a variable is used in a snippet, it will have the same value in all topics in the output. The value will be the default for the variable or whatever is defined for that output.

There are cases where the variable needs to have a different value in each topic where the snippet is used, also it may be used more than once in a single topic and need different variable values in each instance. For example the snippet could be a set of steps where just the name of a button changes.

A solution has been identified that allows one value per topic but it requires that the topic title is used and inserted into the snippet as a Field Variable. That has shortcomings in that it requires "odd" titles and the snippet cannot be used more than once in any topic with different values.

What is needed is the ability to include in a snippet the name of a hybrid variable, for now let's call it InstanceVariable. Wherever a snippet is included in a topic and that snippet includes an InstanceVariable, RH should prompt for the variable value to be used.

This would enable snippets to be the basis of content rather than having to be complete and greatly enhance their value.

[Captiv8r]

Hi Peter

Well put!

I suppose for the "instance variable", maybe "topic variable"? Define a variable at the global level, then have an ability in each topic to specify within the topic what the variable value should contain. I could easily see it applying in a very similar manner to the way they began storing the meta information in the topics. Things like Topic level keywords, Status, Hours, things like that.

I guess we might even think of it as similar to our styles. The global variable would be similar to a style sheet .CSS files. But the same rule can be defined more granular (the embedded style) and overrides the global.

I'm liking this! Rick

[Peter Grainge]

I was thinking these variables would just be for snippets as variables seemed to cater for topics as they are. On that basis I was going to change the term to SnippetVariable.

Not sure about topic variables. If you only need a few variations, then two or three variables give you what you want. If you have lots of variations, then it seems like it is not really a variable anymore and just plain old content.

Perhaps others could chip in and give us a view?

[kmaddox1]

Hi Peter,

Your description sounds good to me. But just to make sure I get it, is this how it should work?

1. Ceate a snippet and include within it one or more different "SnippetVariables." (These are different that ProjectVariables, which affect all topics throughout the project.)

2. Import this snippet into a topic.

3. When prompted, specify topic-level values for SnippetVariables A, B, and so on. At this point (or when generating output/view?), the values are "merged" with the snippet text and included into the topic. To edit this text, you either need to go back to the source snippet or you can "add" the snippet to the topic, which breaks its link to the original.

4. Repeat step 3 for each topic where the snippet is used, specifying new values for the different SnippetVariables.

5. As needed, edit the value of the SnippetVariables to change the information used in a topic (all other topics are untouched).

6. As needed, edit the snippet or change the meaning of a ProjectVariable to change all topics at once.

One more request. It would be great if a SnippetVariable could be used as a placeholder for an image file. (That is, imagine the case where my boilerplate instructions include a screen shot, but the actual image varies from topic to topic.)