Clipart Gallery Extension HowTo

The present status of including clipart extensions in OpenOfffice.org is not very easy, and there are a few pitfalls and bugs to avoid.

Create a new Clipart Gallery Theme

If you already finished your new Gallery theme, just skip this paragraph...

Creating a Gallery theme for your local usage is quite easy, but in most cases the images are not embedded, but linked. To embed them you have to follow three steps:

• Open Draw or Impress (it doesn't work with Writer because there images are included in frames)
• Add the images you want to include in the gallery to the document with "Insert" - "Picture" - "from file" or just copy&paste - but take care that you not only add a link (like c&p from Internet).
• Open the Gallery, create a "New Theme" and name it according the topic of your images.
• Click on one of the images in your document, keep the mouse button pressed for about 2 seconds (until the mouse turns to a rectangle) and drag it to the gallery.
• Change the new gallery item's name from "dd<number>" to a better name.
• Repeat the last two steps until you added all the images to the gallery.
• Get the theme's name (sg<number>) from the theme's properties.
• Search the gallery files with this name in your file system (probably to be found under <your_openoffice.org_path>/3/users/gallery/ )
• copy them to the folder where you want to create your extension.

If you want to include more than one gallery theme in your extension, just repeat these steps.

Create an extension

OpenOffice.org extensions are XML based containers that provide additions to our application whether these are code, UI changes or gallery content as in our case. For more information please have a look at the Extensions wiki page.

Clipart Gallery extensions must contain some information like the gallery files, but they should contain some additional content too.

A very simple gallery theme can be created by usage of this file, where you only need to add your sg<number>.sdg sg<number>.sdv sg<number>.thm files to the folder "gallery" included in the archive file (unzip and zip it or use an archive manager).

But if you want to provide more information with your extension, like a name different from the file name, a version numbering, license agreement, description or icon, you should give this extension a try. It contains a short version of this HowTo, so you might work on it without continuous Internet access...

You'll need to modify this extension a bit, but it's not so hard, if you can use a text editor:

• Extract the extension on your file system.
• Add the gallery files to the folder /gallery/ inside this extracted folder.
• Decide on a few points:
  • Which license do you want? The folder contains two license files: license_LGPL.txt and license_PDL.txt. If you want to use one (or both) of them, just remove the one you don't want to use. In case you use PDL, the file license_PDL.txt will have to be edited: You'll have to provide: the TITLE of the extension, your PRENAME and NAME, the YEAR of release and your EMAIL@ADDRESS. If you prefer a different license, just replace both of the files.
  • Do you want to provide a specific icon that shows up at the extension manager? If so, just create a png file (48x48 pixel), name it icon.png and replace the current file.
• Edit the file "description.xml" with the editor of your choice.
  • add a version number (necessary for automatic update feature)
  • provide an extension name (mandatory)
  • optional changes:
    • license agreement: If you want the user/admin to accept a license during installation, uncomment the paragraph <registration> and put the license text in the folder /resources/ (file name: license_en.txt or any other file you specify here).
    • icon: You might change this paragraph instead of renaming your file...
    • description: A short text that shows up in the extension manager - if you don't want to provide it, remove/comment the paragraph <extension-description>, otherwise you should modify the file "description_en.txt" in subfolder /description/.
• finally zip compress the folder, rename the archive to <MyExtensionName>.oxt and test the new extension with a version of OpenOffice.org that doesn't contain the gallery theme (probably you will have to remove the gallery theme(s) you created on building the extension...).

Upload and Promote Your Extension

After such hard work you'll probably want to share your extension with other OpenOffice.org users. The best way to do so, is to upload the extension to the extension repository. As there is no graphical overview on existing Clipart Gallery extensions at the repository, you might want to add a link (with image) to your extension to the Clipart Gallery page at the wiki. It's easy - just copy the way other extensions are presented.

Shortcomings, Bugs and Backdrafts

The present Clipart Gallery in OpenOffice.org needs major rework, but even if this work is just going to start, we don't want to wait for several months or years until the release of a new version. Therefore it is necessary to avoid the same file names (sg<number>.sdg etc) inside one instance of OpenOffice.org. Otherwise the new gallery will not show any images.

To reduce the risk of double naming, all extensions presented at the Clipart Gallery page show the <sg>number in their file name. Please change the sg<number> of your gallery files in /gallery/ , if they interfere with the sg<number> of any other extensions presented on the wiki page.

There is no possibility to add language dependent names to the gallery theme or the single items. This will have to wait until the "new" gallery...