Windchill+ Administration Help > Windchill+ Implementation Management > Customization > Customization Patterns > Persistence Management > Working with Rich Text Images Using PersistableAdapter API
Working with Rich Text Images Using PersistableAdapter API
This topic explains how to create, persist, update, and retrieve images embedded in HTML text attributes by using the PersistableAdapter and supported helper APIs.
Terminology
Term
Description
HTML text attribute
An attribute with the HTMLText data type.
HTML text holder
An object (such as a change notice or document) that contains one or more HTML text attributes.
filename attribute in <img>
A platform‑defined attribute used to link an <img> tag in the HTML text to an actual image file stored in Windchill.
ApplicationData
The content object that represents a stored image file in Windchill.
Create Operation
Creating rich text content with images involves three main steps:
1. Generate unique image file names.
Before creating the rich text content, generate unique file names for the images that will be embedded.
API:
RichTextImageHelper.generateUniqueImageNames(Map<String, Integer> imageTypeCountMap)
Example:
Map<String, Integer> imageTypeCountMap = new HashMap<>();
imageTypeCountMap.put("png", 1);
imageTypeCountMap.put("jpg", 1);
imageTypeCountMap.put("jpeg", 1);

Map<String, List<String>> uniqueNames =
RichTextImageHelper.generateUniqueImageNames(imageTypeCountMap);
Example output:
◦ 550e8400-e29b-41d4-a716-446655440000.png
◦ 6ba7b812-9dad-11d1-80b4-00c04fd430c8.jpg
◦ 6ba7b810-9dad-11d1-80b4-00c04fd430c8.jpeg
* 
• Rename your actual image files to exactly match these generated names.
• File names and extension must match the filename attribute used as image reference in <img> tag.
2. Build the rich text HTML and create the object.
Create the rich text content and include one <img> tag for each image.
◦ Each <img> tag must include a filename attribute.
◦ The filename value must match one of the generated names.
◦ The order of <img> tags controls how images appear when the rich text is rendered.
◦ Optional image styling can be applied using the style attribute.
Example HTML:
String htmlText = "<p>Some Rich Text"
+ "<img filename=\"550e8400-e29b-41d4-a716-446655440000.png\" style=\"width: 300px; display: block; vertical-align: top; margin: 5px auto; text-align: center;\" />"
+ "<img filename=\"6ba7b812-9dad-11d1-80b4-00c04fd430c8.jpg\" style=\"width: 200px;\" />"
+ "<img filename=\"6ba7b810-9dad-11d1-80b4-00c04fd430c8.jpeg\" style=\"width: 150px;\" />"
+ "</p>";
Set this HTML string on the HTML text attribute and persist the object using the PersistableAdapter API.
Example:
TypeDefinitionReadView type = TypeDefinitionServiceHelper.service.getTypeDefView("wt.change2.WTChangeOrder2");
Locale locale = SessionHelper.getLocale();
PersistableAdapter pa = new PersistableAdapter( type.getName(), locale, new CreateOperationIdentifier());
pa.load("name", "theChangeNoticeComplexity", htmlTextAttribute);
pa.set("name", "MyChangeOrder_" + System.currentTimeMillis());
pa.set("theChangeNoticeComplexity", ChangeNoticeComplexity.BASIC);
pa.set(htmlTextAttribute, htmlText);
TypeInstanceIdentifier tii = pa.persist();
TypeInstance ti = TypeInstanceUtility.newTypeInstance(tii);
ContentHolder createdObject = (ContentHolder)
TypeInstanceUtility.getPersistable(ti);
3. Persist the image files.
After the object is created and the HTML text attribute value is saved, persist the actual image files using the supported helper API.
API:
RichTextImageHelper.persistRichTextImages (ContentHolder htmlTextHolder, String htmlTextAttribute, Map<String, File> imageFiles)
This API associates the image files with the HTML text attribute based on the filename values specified in the <img> tags.
* 
Each file name must match the corresponding <img filename="..."> value in the HTML.
Example:
File img1 = new File("/path/to/550e8400-e29b-41d4-a716-446655440000.png");
File img2 = new File("/path/to/6ba7b812-9dad-11d1-80b4-00c04fd430c8.jpg");
File img3 = new File("/path/to/6ba7b810-9dad-11d1-80b4-00c04fd430c8.jpeg");

Map<String, File> images = new HashMap<>();

images.put("550e8400-e29b-41d4-a716-446655440000.png", img1);
images.put("6ba7b812-9dad-11d1-80b4-00c04fd430c8.jpg", img2);
images.put("6ba7b810-9dad-11d1-80b4-00c04fd430c8.jpeg", img3);

RichTextImageHelper.persistRichTextImages(createdObject, htmlTextAttribute, images);
When you complete this step successfully, the images are stored as content and are logically linked to the HTML text attribute.
Update Operation
When you modify rich text content that contains images, whether you add new images or remove existing ones, you must call RichTextImageHelper.persistRichTextImages after saving the updated HTML text attribute value.
This API handles synchronization between the HTML content and the persisted image files.
It persists any new image files referenced in the updated HTML. It automatically deletes images that are no longer referenced in the HTML text.
Update Steps:
1. Update the rich text HTML as required:
◦ To add images, generate new unique file names using RichTextImageHelper.generateUniqueImageNames.
◦ Use these image names as a reference (filename attributes) in the <img> tags.
◦ To remove images, remove the corresponding <img> tags from the HTML.
◦ To replace images, remove the old <img> tags add new reference (filename attribute) tags.
2. Call the API persistRichTextImages with the updated object, the HTML text attribute name, and a map that contains only the new image files to persist.
API:
RichTextImageHelper.persistRichTextImages(
ContentHolder htmlTextHolder,
String htmlTextAttribute,
Map<String, File> imageFiles
)
Use case scenarios:
• For adding images, include the new image files in the map.
• For deleting images, pass an empty map. The API detects images that are no longer referenced in the HTML and deletes them.
• For adding and deleting images, include only the new image files in the map. The API persists the new files and removes the images that are no longer referenced.
Example 1 — Add a new image to the existing rich text:
Map<String, File> newImages = new HashMap<>();
newImages.put(
"newly-generated.png",
new File("/path/to/newly-generated.png")
);

RichTextImageHelper.persistRichTextImages(
updatedObject,
htmlTextAttribute,
newImages
);
Example 2 — Remove an image from existing rich text:
Remove the <img> tag from the HTML, save the updated attribute, and then call:
Map<String, File> emptyMap = new HashMap<>();

RichTextImageHelper.persistRichTextImages(
updatedObject,
htmlTextAttribute,
emptyMap
);

or

RichTextImageHelper.persistRichTextImages(
updatedObject,
htmlTextAttribute,
null
);
The API compares the <img> tags in the current HTML with the stored image content and deletes any images that are no longer referenced.
Rendering Rich Text Images with Downloadable URLs
Rich text stored in attributes contains <img> tags that reference images by filename. To render the rich text with <img> tags that include a valid content download URL in the src (source) attribute, use the following API.
RichTextImageHelper.insertSrcForImgTags(ContentHolder contentHolder,HTMLText htmlText)
Usage:
• htmlTextHolder: The object that contains the HTML text attribute.
• htmlText: The object representing the rich text value that contains <img> tags with filename attributes.
This API updates the HTML so that each <img> tag includes a src attribute pointing to the appropriate content download URL.
Read Operation — Retrieving Associated Images
To retrieve images that are stored for HTML text attributes, use one of the following APIs:
API
Description
getRichTextImages(ContentHolder htmlTextHolder, String htmlTextAttribute)
Returns images associated with a specific HTML text attribute.
Example:
WTSet persistedRichTextImages = getRichTextImages(htmlTextHolder, htmlTextAttribute);

Collection richTextImagesCollection = persistedRichTextImages.persistableCollection();
for (Object appData : richTextImagesCollection) {
ApplicationData richTextImage = (ApplicationData) appData;
The returned WTSet contains application data objects. All supported application data APIs can be used to work with these images.
Was this helpful?