I am looking at using the Hazard Statement elements as part of the DITA framework. I like the idea of assigning the applicable attribute type (danger, caution, warning) and having the banner change automatically. For example, when you chose type: danger, it pulls up a red banner with a warning symbol.
Here is my question, where and how to I change how this banner looks? I like the idea of having the banner populate by simply assigning the type attribute, but I would like to change the color, symbol and placement of text. I can't for the life of my figure out where Framemaker keeps or pulls this graphic from.
I know I could use the hazardsymbol element and insert my own symbol, but this takes away from the functionality of having DITA "lock down" which symbol goes with which type of hazard statement.
Please see attached example.
Take a look at the reference pages.
OMG thank you! I can't believe I could not find any documentation about Reference Pages. This should be what I need.
For some reason when I make changes to the Reference Page in document the changes don't stay after I save. I suspect this page resides in a linked template file somewhere.
Yes, you have to change the reference page in the templates located in the Framemaker structure folder of C drive. For example, for FM 2017 version, the templates are located at:
C:\Program Files (x86)\Adobe\Adobe FrameMaker 2017\Structure\xml\DITA_1.2\app\technicalContent\template
The path may vary based on the versions. Before making any changes to these template files, make sure you take a backup of the original files.
Wow, that is nested - but found it! We currently do have a separate set of templates in a Mercurial versioning system.
One last question and I think I can call this thread "answered". Do I have to update the Reference page for each .FM file?
Here would be the list:
It's not the end of the world - could always copy and paste, but might as well as if Reference Pages can be shared/linked.
Depends on your requirement. If you are going to use all of these XML types, then it is better to configure all template files. If you are just going to use concept and task (where the warnings are normally used), then you can configure only these files. Proceed as per your requirement.
This is one of the biggest problems with the default implementation of DITA in FrameMaker .. making the DITA structure app model parallel with the modular nature of the DITA DTDs. While logically, this makes perfect sense, it's a total train wreck from a maintenance perspective, and in reality provides virtually zero benefit. In most cases (or, all cases), the formatting and reference objects you want in your concept topics are the same as in your task and reference topics (as well as all other topic-based topic types). Forcing the user to update in parallel, all of these templates and underlying EDDs to make simple formatting changes is just cruel (and error prone). And .. when you build a book, these all get merged into the same file anyway, so any format collisions need to be resolved/normalized.
I promote using a single structure app that supports all (well, most) topic types. (One app for Map, and one for Topic.) This is possible by using the ditabase DTD instead of the topic-based DTDs. This is all perfectly valid and legal from a DITA perspective, and lets you manage one structure app rather than many.
This is the model that DITA-FMx uses (my plugin that replaces the default DITA support in FM). While you can get this using DITA-FMx, you can also do it in default FM. Grab the DITA-FMx trial and steal (clone and rename) the Topic structure app. You'll need to make slight modifications for it to work properly in default FM-DITA, but it should work fine, and will simplify your life considerably.
Scott, thanks for the reply and the suggested work-arounds. I am fairly new to FrameMaker and even newer to DITA, but reading between the lines it appears that the DITA integration with FrameMaker is a bit "unfinished". And I fully agree that any reference objects should be available to all topics and should look the same. I would not want a Danger message to look on way in a Concept and another way in a Task.
Again some of this is high-level for me, but I understand that ditabase is depreciated, but it could still be used for a container for re-use information. Is this then where you suggest I keep/store my reference objects?
I think I've opened a can of worms, but we are looking at leveraging DITA and FrameMaker (which is our adopted model for single-sourcing) so we better make the most of it.
To be fair .. I wouldn't say that the DITA implementation in FM is unfinished .. there are just some areas that could be improved upon.
The ditabase DTD is included with DITA 1.3. While it's not a recommended method for authoring, it is available for use where needed. I'm not seeing anything in the spec that says that this is deprecated.
However, to answer your question .. no .. you can't add your reference objects to the ditabase template and have them available in all topics. That would be nice, but the modularity of the structure apps doesn't go that far. Basically, the way the default FM-DITA is set up is to have one app for each topic type. If you look in the structure application definitions file, you'll see all of the DITA apps. Each app has a template (the files listed earlier in the thread), plus read/write rules, an app definition, and other related files. The EDD (the document that defines the rules for applying formatting/styles to elements and element structures) is embedded (imported) within the template. When making modifications to a structure app, you update the template for basic formatting changes, but you'll need to edit the EDD when you need to change the way formatting is applied to elements. The EDDs are set up as nested documents, where the common/reused bits are imported as text insets. This nesting goes up to 5 levels (I believe) deep. This is where things start to get really hairy when you want to make changes to the formatting. In theory, making a change to an underlying EDD inset, will get applied to all of the top-level EDDs in the other apps, but this isn't automatic .. you have to manually open the right files and update the insets, then you have to import the updated top-level EDDs into the appropriate templates.
If you want to avoid this maintenance mess, you might consider trying DITA-FMx, or at least adopting the structure app model used by DITA-FMx.
Contact me off list for more details.
I completely agree with you on this. The development team has to streamline a few of the things to make a writer's life easier. But the flipside is since the help guides available for FM DITA are so badly managed, if they do any new changes to amend these flaws, the user again has to suffer finding help topics for these new changes. When I started to migrate to DITA from unstructured, I had to struggle a lot whenever I got struck.
I am getting there, but any images I have added to the Reference Page in the DITA Template will show up as a gray box when I create a new topic (based on the template).
This message appears: "Cannot display some imported graphics. The images will appear as a gray box."
The thing is, my Object Properties clearly states a Referenced Path for this graphic. So I don't know why it should not render the graphic.
Check the reference page in the generated FM file. I'll bet it's not there. You're adding it to one of the many templates, but I'll bet that you need to add it to the template that's used when generating a book. That's likely a different template. I don't know which one .. maybe ditabase? This is why I can't work on generating output from default FM-DITA .. the apps are too crazy. I'm sure someone knows though.
I have been searching how to use these hazard frames which can be found from reference pages. Could you be more specific, how those can be taken in use from the reference pages?
Please see my question in detail How to use hazard.notice frames from reference pages for DITA?
I think I'm ready to throw in the towel with trying to create customized Hazard Statement objects.
While I know where to create/edit Reference Page items, when I try to use a them (in this case a the graphic), I get the message "Cannot display some imported graphics. The images will appear as a gray box."
This only shows when I try to create a topic based on the Template File. I tried both SVG and JPG.
Not trying to push my tool (DITA-FMx), but did want to mention that with the last update I added some very cool support for hazardstatement authoring and publishing. I worked with some customers to make sure it was actually useful and usable. It's not trivial to switch to DITA-FMx, but it'll give you nice hazardstatement support plus many other nice features. Here's the documentation on the new feature ..
Appreciate it! I'd love to try out DITA-FMx, but I was hoping I could get it to work within just FrameMaker, even if only in one topic. I could then demonstrate to stakeholders that there are efficiencies in using both this element and maybe your plugin. I'll read up on your documentation! Cheers.
I can't recommend Scott's method and help on these things more highly, including DITA-FMx.
In the long run you will save an amazing amount of money and headache by following his lead.
He did an amazing job with my client a few years ago, (huge DITA conversion and implementation, including integration with Adobe Experience Manager) and is one of only a very few people I would trust for Fm DITA questions.
I have had some time to look over your documentation. Can you quickly explain what your goal was for implementing a plugin for the Hazard Statement element? It would appear that out-of-the-box, FrameMaker DITA does not allow for a lot of customization of this element (which I am learning). And I imagine your plugin allows for some standardization (and hopefully) reuse of the way the Hazard message and associated symbols display. Is this a fair interpretation?
The learning curve is big with DITA...from the .exe redirection files, to the .ini files, etc. I'm just a technical writer....lol.
Note that the plugin isn't just for hazard statements .. it's a complete replacement for the DITA authoring and publishing processes in FrameMaker (and works with FM8 and later). The hazard statement support is just one of the many features. You can read the feature comparison between DITA-FMx and default FM-DITA, here..
(This feature comparison hasn't been updated recently, so it's a bit out of date, but you'll get the idea.)
The reason I added the hazard statement support into DITA-FMx was because it was requested by customers, since they were unable to use this elements in any useful way. Most of the features in FMx are added through customer requests.
I hope that helps,