13 Working With Fragments
This section covers the following topics:
13.1 About Fragments
When you first design a page template, you generally start with the basic look and feel of the site, using background colors, graphics, text, and a table layout. This kind of information opens in the same way on every page of the web site, or a section of the web site. You can, therefore, add this information directly to the page template, subtemplate, or region template in source or design view.
A fragment can be a single line of text (such as a copyright notice), or it can be a complex collection of scripts performing client-side and server-side actions (such as a JavaScript-based menu).
Just about anything that you add to a page template, subtemplate, or region template can be added as a fragment. How often you use fragments depends on your preference and the requirements of your web site.
13.2 Adding and Editing Fragments
Fragments can be added and edited using the Toolbox in Designer. Site Studio includes numerous sample fragments in the Toolbox that you can use or customize for your own (see Section 13.4, "Fragments in the Toolbox"). To use a fragment, simply place your cursor on the template where you would like the fragment to appear and then click the desired fragment in the Toolbox.
You can customize the way a fragment appears on a template by changing its parameters in the Fragment Parameter Values dialog, which you see when you add the fragment to a template.
The fragments contain parameters so that you can customize the fragment each time you use it on a template. If there's a setting that you're unable to change in a parameter, you can always open the fragment in the Fragment Editor and customize it there; even add your own custom parameter if you like.
13.3 Fragment Handling in Templates
Page templates, being complete HTML documents, have a <HEAD> and <BODY> in their code. Subtemplates and region templates, however, do not have a <HEAD> section. You must be aware of this distinction when placing a fragment, and also when creating and editing fragments.
The snippets inside of a fragment have a designated location of head, drop-point, top-of-body, or bottom-of-body. These designations are made when creating or editing fragments in the Fragment Editor dialog (see Section A.57, "Fragment Editor Dialog"). Those snippets designated with a head location must be placed on a template with a <HEAD>; that is, they must be placed on a page template because they require the header to work. If you place a fragment that has a snippet with a head location on a region template or a subtemplate, then the fragment cannot work.
When you put a fragment on a page template, this includes information in the XML data island, specifically in the <SSINFO> tag. When you put a fragment on a subtemplate or a region template, then a wcmFragment tag is placed in the HTML. In both cases this can be seen in source view.
It is recommended that, whenever possible, you create fragments with a single body snippet. The fragment can then be used in any situation, whether it is on a page template, a subtemplate, or a region template.
13.4 Fragments in the Toolbox
Site Studio includes numerous out-of-the-box fragments that you can begin using right away without knowing how to create or edit a fragment. Using the sample fragments is a great way to add instant functionality to your web site while learning about the practical use and potential of a fragment.
The sample fragments are available in the Toolbox and are divided into four categories:
-
Navigation Fragments: This category contains fragments that provide site navigation for your web site (navigation bar, breadcrumbs, search box, and so on). The beauty of a navigation fragment is that it automatically reads your existing site hierarchy and converts the sections into hyperlinks that display in a navigation menu. Consequently, you can update and change your site hierarchy, and those changes are seen immediately on your web site. For a description of these fragments, see Section C.1, "Navigation Fragments."
-
Dynamic List Fragments: This category contains fragments that provide advanced contribution features for your web site, specifically the ability to query for contributor data files and native documents in the content server. Contributors can then use the Contributor application to add, remove, and edit the files in the list (see Section C.2, "Dynamic List Fragments").
-
Static List Fragments: This category contains fragments that provide advanced contribution features for your web site, specifically the ability to create a structured layout of elements (WYISIWYG, plain text, image, and custom). Contributors can then use the Contributor application to add, remove, and edit rows and columns of information in the list (see Section C.3, "Static List Fragments").
-
Other Fragments: This category contains miscellaneous fragments that you may find useful for your site (a copyright line, an embedded Flash presentation, a dynamically converted native document, Manager, and so on). For a description of these fragments, see Section C.4, "Other Fragments."
13.5 Filtering Fragments in the Toolbox
The Toolbox in Designer displays all of the fragments that are available to you as you build your web site. As you and other designers introduce fragments to the site (or sites), however, the total number of fragments in the Toolbox can quickly become unmanageable.
You can control which fragments display in the Toolbox by filtering them based on their scripting language, whether they belong to your site or not, and whether you've introduced them or they came with Site Studio.
To filter fragments in the Toolbox, perform these tasks:
-
From the View menu, select Customize.
-
Click the Miscellaneous tab.
-
To display only the fragments written in the same language as your site (HCSP/JSP or ASP), check Filter fragments in other languages.
-
To display only the fragments that belong to your site (and not other sites), check Filter libraries from other sites.
Fragments in fragment libraries not identified as part of your site no longer appear in the Toolbox. To make a fragment part of your site, add it as a site asset to the "Fragment Libraries" category.
-
To display only the fragments that you created (and not the default ones that ship with Site Studio), check Filter default libraries.
-
Click Close to close the Customize dialog.
One reason you may want to show all of the available fragments on the server is to copy one of those fragment and make it part of your site.
13.6 Adding Fragments to a Template
You can use the Toolbox to add fragments directly to a template while working in design or source view.
To add a fragment, perform these tasks:
-
Place your cursor in the template where you want the fragment to appear.
If you're adding a list fragment, It may be necessary to first create a contribution region and then place the fragment in that region.
-
In the Toolbox, click a fragment category: Navigation Fragments, Dynamic List Fragments, Static List Fragments, or Other Fragments.
-
Click the desired fragment (for a description of each fragment, see Appendix C, "Sample Fragments").
-
If the fragment contains parameters, you are prompted for additional information in the Fragment Parameter Values dialog (see Section A.65, "Fragment Parameter Values Dialog").
-
Enter the appropriate values in the fields provided and then click OK to add the fragment.
The fragment displays on your template where your cursor was last located.
Many of the sample fragments insert a small text or a graphic as a visual aid so that you know where a fragment is located on a template. This small marker is known as the design view code. The design view code is used because many of the fragments contain dynamic content and server-side scripts that must be viewed in a web browser on the web site to be seen properly.
The placeholder does not necessarily represent how the fragment appears on your web site. You can change the placeholder in the Fragment Editor, if you like (see Step 5 in Section 13.12.4, "Adding, Editing, and Deleting Fragment Snippets").
13.7 Previewing Fragments
Previewing a fragment can be useful to determine what the fragment looks like and how it works before making it a part of your template. You can preview fragments using the Preview option in the right-click menu of the Toolbox, or using the Preview button in the Fragment Editor (see Section 13.12, "Using the Fragment Editor").
This section covers the following topics:
-
Section 13.7.2, "Choosing Different Parameters for a Fragment"
-
Section 13.7.3, "Choosing Different Parameters When Adding a Fragment"
13.7.1 Previewing a Fragment
To preview a fragment, perform these tasks:
-
In the Toolbox, click a fragment category: Navigation Fragments, Dynamic List Fragments, Static List Fragments, or Other Fragments.
-
Right-click the desired fragment and choose Preview.
-
If the fragment contains parameters, you are taken to the Fragment Parameter Values dialog (see Section A.65, "Fragment Parameter Values Dialog").
Enter the appropriate values in the fields provided and click OK.
-
The Fragment Preview dialog opens (see Section A.66, "Fragment Preview Dialog"), where you can see what your fragment looks like.
-
Click a section in the site hierarchy pane to see how the fragment appears in different sections of the web site.
If a section in the site hierarchy is not included in your site navigation, has no primary page associated with it, or is pointing to an external URL, then you cannot select it and preview it in this dialog.
-
To see what the fragment looks like with different parameter values selected, click Change Parameter Values, enter the appropriate values in the fields provided, and then click OK to return to the Fragment Preview dialog.
-
Click Finished when you're done previewing the fragment.
For a description of all the sample fragments and their parameters in the Toolbox, see Appendix C, "Sample Fragments."
You cannot preview a static list fragment in the Fragment Preview dialog because the list requires a contributor data file with content in it to be viewed properly.
13.7.2 Choosing Different Parameters for a Fragment
You can customize the way a fragment appears by changing its parameters in the Fragment Parameter Values dialog when you preview a fragment or add it to a page template, subtemplate, or region template. You can also change those values after you've added the fragment.
13.7.3 Choosing Different Parameters When Adding a Fragment
To choose different parameters when adding a fragment, perform these tasks:
-
Place your cursor in the template where you want the fragment to appear.
-
In the Toolbox, click a fragment category: Navigation Fragments, Dynamic List Fragments, Static List Fragments, or Other Fragments. Then click the desired fragment.
-
In the Fragment Parameter Values dialog (see Section A.65, "Fragment Parameter Values Dialog"), enter the appropriate values in the fields provided, and click OK.
or
If you're adding a list fragment to a contribution region, enter the appropriate values in the Element dialog and then click Parameters to change its parameters.
Click OK twice to close the Fragment Parameter Values and the Element dialog.
13.7.4 Changing the Parameters of a Fragment
After you've added a fragment to a template, you can still change its parameters and thus its appearance on a web page.
To change the parameters of a fragment, perform these tasks:
-
In design view, double-click the fragment.
or
In source view, right-click the fragment and choose Edit Fragment Instance.
-
Change the desired parameter values in the Fragment Parameter Values dialog (see Section A.65, "Fragment Parameter Values Dialog").
-
Click OK.
You cannot change the parameter values of a fragment that has been added to a page template if that fragment contains snippets included as type "simple" (see Section 13.12.4, "Adding, Editing, and Deleting Fragment Snippets").
For a description of each parameter included in the sample fragments, see Appendix C, "Sample Fragments." Please note, however, that some fragments may not contain parameters.
To add parameters to a fragment or to further customize the fragment, you can edit the fragment in the Fragment Editor (see Section 13.8, "Editing Fragments").
Note:
The options you choose in the Fragment Parameter Values dialog apply only to this one instance where you added the fragment to a template. You can choose different values each time you add a fragment to a template without affecting the appearance of the same fragment used elsewhere on your site.13.8 Editing Fragments
There are two ways to change the appearance of a fragment on your web site: change its parameters (see Section 13.7.2, "Choosing Different Parameters for a Fragment") or change the fragment.
By editing a fragment, you can completely change its appearance and functionality to meet your needs. You can even create your own parameters so that you can ensure editing decisions later, when you actually add the fragment to a template.
There are two ways to edit a fragment:
13.8.1 Editing a Copy of a Fragment
Editing a copy of a fragment can be useful when you want to edit a fragment without altering the original. You also must edit a copy of a fragment when the fragment library it belongs to is checked out by another user or labeled as read-only (see Section 13.13.3, "Making a Fragment Library Read-Only").
Note:
The fragments that come with Site Studio are read-only, so to edit them, you must choose this option.To edit a copy of a fragment, perform these tasks:
-
In the Toolbox, click a fragment category: Navigation Fragments, Dynamic List Fragments, Static List Fragments, or Other Fragments.
-
Right-click the desired fragment and choose Copy and Edit.
-
The Properties for Fragment dialog (see Section A.58, "Properties for Fragment Dialog") opens, where you can specify individual properties for the fragment.
-
Click OK to close the fragment properties dialog.
-
The fragment opens in the Fragment Editor, where you can start making changes to the fragment (see Section 13.12, "Using the Fragment Editor").
-
When finished making changes, click the Save icon (Figure 13-3) in the toolbar (or click File then Save) and follow the steps outlined in Section 13.13.2, "Saving a Fragment in a Fragment Library."
The fragment displays in the Toolbox with the other fragments, and it is available to every site in the content server.
13.8.2 Editing a Fragment
After you (or another designer) adds a fragment to the Toolbox, you can start editing it right away.
Note:
You cannot edit the fragments that come with Site Studio directly because they are read-only.To edit a fragment, perform these tasks:
-
In the Toolbox, click a fragment category: Navigation Fragments, Dynamic List Fragments, Static List Fragments, or Other Fragments.
-
Right-click the desired fragment and choose Edit.
-
The fragment opens in the Fragment Editor, where you can start making changes to the fragment (see Section 13.12, "Using the Fragment Editor").
-
When finished, click the Save icon (Figure 13-4) in the toolbar (or click File, then select Save).
-
On the Assign Info Form in the content server, enter the appropriate metadata for the library and then click Assign Info.
Note:
When you edit a fragment in the Fragment Editor, the fragment library (that the fragment is stored in) is checked out of the content server, and it is checked back in when you close the Fragment Editor. (It is also checked out and checked in each time you save the fragment.) This prevents designers (assuming your organization has more than one) from encountering sharing violations or overriding each other's work.
It may occasionally be necessary to click the Refresh icon (Figure 13-5) in Designer to see the most current list of fragments in the Toolbox (which reads them from the content server).
In Site Studio, it is good practice to create a copy of a fragment and then edit that fragment instead of editing the original. There are several reasons for this:
-
You can quickly and easily revert to the original fragment if needed (in case anything goes wrong with the fragment you're editing).
-
You can quickly get started with your own fragment without re-creating everything in an existing fragment (much like creating a page template based on an existing page template).
-
You reduce the chances of overwriting another designer's work and consequently, creating unpredictable results on a web site. The reason for this is that the fragments you create and edit in Designer are stored in one place in the content server. They appear in every instance of Designer that is connected to the same content server, and therefore, multiple designers can end up using the same fragment on different web sites.
13.9 Creating a New Fragment
In addition to editing fragments and creating fragments from existing ones (see Section 13.8, "Editing Fragments"), you can create a fragment from scratch and add your own content to it. This is a good choice to introduce functionality or use existing content from another web site (that wasn't created with Site Studio).
To create a fragment, perform these tasks:
-
From the File menu, select Fragment, then select New.
-
In the New Fragment dialog, enter property values for the fragment (see Section A.58, "Properties for Fragment Dialog").
-
Click OK to close the fragment properties dialog, which opens the Fragment Editor.
-
In the Fragment Editor, add the desired snippets, assets, parameters, and elements (if it's a static list) to the fragment. For more information, see Section 13.12, "Using the Fragment Editor"
-
When finished making changes, click the Save icon (Figure 13-6) in the toolbar (or click File then Save) and follow the steps outlined in Section 13.13.2, "Saving a Fragment in a Fragment Library."
The fragment displays in the Toolbox with the other fragments and is available to every site on the content server.
13.10 Deleting a Fragment
You can delete a fragment from a template in the same way that you delete tables, graphics, and other objects.
To delete a fragment, perform these tasks:
-
Select the fragment, and press the Delete key on your keyboard.
or
In source view, right-click the fragment code and choose Delete Fragment Instance.
-
Click Yes to confirm the deletion.
The fragment instance is removed. The fragment itself remains in the Toolbox, and you can continue using it on other templates.
13.11 Deleting a Fragment in the Toolbox
You can delete a fragment in the Toolbox, which also deletes it from the content server.
Note:
Fragments in Site Studio are stored in Oracle Content Server and are available to every web site on the server. If you delete a fragment for one web site, other web sites using that same fragment is affected. You should, therefore, first verify that the fragment is not being used elsewhere before you delete it.To delete a fragment in the Toolbox, perform these tasks:
-
In the Toolbox, right-click the desired fragment.
-
Choose Delete.
-
Click Yes to confirm the deletion.
The fragment is no longer included in the Toolbox.
13.12 Using the Fragment Editor
A fragment is a container for code ( HTML, XML, JavaScript, Idoc Script), files referenced by that code (graphics, CSS, additional scripts, and so on), and parameters that govern how that code is added to a template.
The file that stores this information is written in XML and is stored in the content server with the fragment assets. The XML file and the fragment assets collectively are called a fragment library.
You can view and edit fragments and the files referenced by that fragment using the Fragment Editor.
Using the Fragment Editor, you can modify existing fragments and create your own fragments. You can turn just about any piece of code or functionality into a fragment that can be added to a template and still managed separately from the template.
The following are some tasks you'll perform in the Fragment Editor:
-
Section 13.12.3, "Changing the Icon Associated with a Fragment"
-
Section 13.12.4, "Adding, Editing, and Deleting Fragment Snippets"
-
Section 13.12.5, "Adding, Editing, and Deleting Fragment Assets"
-
Section 13.12.6, "Adding, Editing, and Deleting Fragment Parameters"
-
Section 13.12.7, "Adding, Editing, and Deleting Fragment Elements"
The Preview button in the Fragment Editor performs the same action as using the Preview option in the right-click menu of the Toolbox (see Section 13.7, "Previewing Fragments").
13.12.1 Opening the Fragment Editor
The Fragment Editor can be opened within the Designer application, where it used to view and edit fragments. The Fragment Editor displays in the workspace in the same way that templates display there. In fact, some options in the Designer toolbar also apply to fragments (Cut, Copy, Paste, Save, window controls, and so on).
There are two ways to open the Fragment Editor:
-
Right-click an existing fragment in the Toolbox and choose Edit or Copy and Edit (see Section 13.8, "Editing Fragments").
or
-
From the File menu, select Fragments, then select New (see Section 13.9, "Creating a New Fragment").
13.12.2 Specifying Fragment Properties
Each time you create a fragment in Designer, you are prompted to confirm or create individual properties for the fragment. You can also view and change existing properties from within the Fragment Editor by clicking the Additional Information (Figure 13-8) icon:
To specify properties for a fragment, perform these tasks:
-
Open the Properties for Fragments dialog (see Section A.58, "Properties for Fragment Dialog").
-
Enter a name for the fragment in the Name field. The name displays in the Toolbox.
-
Enter an identification in the ID field. This identifies the fragment and its many parts (snippets, fragment assets, parameters, and so on). The ID also serves as an XML attribute and the base name for the fragment's classes, files, and directories. You cannot change the ID after you assign one to a fragment.
Note:
The ID should be concise and should not contain spaces or non-ASCII characters. -
Choose a language for the fragment in the Language field. The language is used for server-side scripting and must correlate with the web site type.
-
Select idoc or jsp for "hcsp/jsp" sites.
-
Select asp for "asp" sites.
-
-
Choose a fragment type in the Type field. The type determines where the fragment appears in the Toolbox (see Section 13.4, "Fragments in the Toolbox") and certain editing options available in the Fragment Editor. You have four choices:
-
navigation: A navigation fragment provides site navigation for your web site, such as a navigation bar, breadcrumbs, and a search box.
-
dynamiclist: A dynamic list fragment provides advanced contribution features by displaying a list of data files or native documents that a contributor can edit.
-
staticlist: A static list fragment provides advanced contribution features by displaying a structured layout of elements, whereby a contributor can add, edit, and delete rows and columns of information.
-
other: This category of fragments is intended for all other, possibly miscellaneous fragments, such as a copyright, an embedded Flash presentation, and a dynamically converted document.
-
-
Click OK to close the Properties dialog and return to the Fragment Editor.
The Library Name in the Properties dialog denotes the fragment library where the fragment is stored. You choose this location when you save the fragment for the first time (see Section 13.13.2, "Saving a Fragment in a Fragment Library").
Note:
Only ASCII characters should be used for fragment IDs and the names of asset files and folders. This is because the folder within the zip file, which is created automatically for the assets, is named after the fragment ID, and the zip format does not support extended characters. This is true also for the names of any folders used for the assets and for the names of the asset files themselves.13.12.3 Changing the Icon Associated with a Fragment
Each fragment in the Toolbox has an icon associated with it that can be used to differentiate it from other fragments. You can change this icon to something different, perhaps something that more closely resembles the purpose of the fragment.
To change the icon associated with a fragment, perform these tasks:
-
With the fragment open in the Fragment Editor, click the Change icon (Figure 13-10) in the upper left. (This icon changes with each fragment you select. The icon shown here is the one you see for a new fragment.)
-
Click the desired icon in the menu.
The icon displays inside this button in the Fragment Editor, and it displays in the Toolbox when you save the fragment.
13.12.4 Adding, Editing, and Deleting Fragment Snippets
A snippet is the actual text or code that a fragment adds to a template. A fragment must have at least one snippet, which is defined by its insertion point (head of page, body, drop-point, and so on) in the template.
For example, if the fragment adds text to one place on the page, then you can create just one snippet for the fragment. But if the fragment inserts text or code in multiple locations on the page (such as a script that must be placed in the head and the body), then you must create two snippets for the fragment (one for the head and one for the body).
You can add, edit, and remove fragment snippets using the Fragment Editor.
To add or edit a snippet, perform these tasks:
-
With the fragment open in the Fragment Editor, click Add to create a snippet, or highlight an existing snippet and click Properties.
This opens the Snippet Properties dialog (see Section A.64, "Snippet Properties Dialog").
-
Enter a name for the snippet in the Name field. (The name may contain spaces and special characters, if you like.)
-
Beside Location, choose an available option:
-
drop-point: Inserts the snippet where the cursor is located on the template.
-
head: Inserts the snippet in the head (specifically the end of the <HEAD> tag) of the page template.
-
top-of-body: Inserts the snippet at the beginning of the body (immediately following the <BODY> tag) in the page template.
-
bottom-of-body: Inserts the snippet at the end of the body (immediately preceding the </BODY> tag) in the page template.
-
-
Beside Include, choose an available option:
-
simple: Adds the entire contents of the snippet to the template. If parameters are present, their values are added directly to the template, making them a permanent part of the page. The fragment, consequently, is no longer recognized as a fragment and its parameters cannot be modified (see Section 13.7.2, "Choosing Different Parameters for a Fragment").
-
inline: Adds the entire contents of the snippet to the template. As an inline snippet, however, the fragment and its parameters are still recognized as a fragment. You can still move the fragment, delete it, and modify its parameters.
-
reference: Adds a reference to the snippet in the template. As a referenced snippet, not only is it still recognized and managed as a fragment, but you can still edit the fragment in the Fragment Editor and immediately see your changes on the template (or templates if used more than once). This behavior is similar to that of an include file (HTML, CSS, script, and so on) on other web sites.
-
-
Beside Design View Code, enter the text you would like to appear as a placeholder for the fragment in the design view of a template. (This feature is intended for snippets that are inserted at the drop-point or the body of a page template and not the head.)
To open the text editor, click the Additional Information icon (Figure 13-11), enter your text, and then click OK to close the text editor.
-
Click OK to close the snippet properties and return to the Fragment Editor.
-
With the snippet selected, you can add and edit the content of the snippet in the Snippet code text box.
Repeat these steps for every snippet that you would like to add or edit in this fragment. You can add as many snippets as you like.
To delete a snippet, simply highlight that snippet and click Delete.
Fragment snippets can be written in HTML, XML, JavaScript, Idoc Script, JavaServer Pages (JSP), and Active Server Pages (ASP). For ASP and JSP, however, you must place your code in a fragment asset (see Section 13.12.5, "Adding, Editing, and Deleting Fragment Assets") and then reference that code from an inline fragment snippet.
You should avoid the word "BODY" in an inline head snippet because that name conflicts with code used by Site Studio to manage the head and body portions of a page template. If you must use this word in your snippet, then you should either (a) change the include method of the snippet from inline to reference, (b) put the code in a fragment asset (see Section 13.12.5, "Adding, Editing, and Deleting Fragment Assets"), and then include it in your fragment that way, or (c) change the code so that the word "BODY" is split into two parts (two concatenated strings).
If you use the same fragment containing a referenced snippet on multiple web sites on the content server, then any changes you make to that fragment immediately affect all web sites where it is used. If this is not your intention, then you should create different fragments for each site (see Section 13.8.1, "Editing a Copy of a Fragment").
Note:
With ASP fragments, you can only include a snippet using the "simple" or "inline" method. Including by "reference" is not available because of the way ASP code handles includes.13.12.5 Adding, Editing, and Deleting Fragment Assets
Assets are the files that are referenced from within a fragment, specifically from within a snippet in the fragment. A graphic, a cascading style sheet, and a standalone JavaScript file (see first note below for implementing ASP or JSP) are all frequently used assets. When you add an asset to a fragment, it becomes a part of the fragment and is managed in a fragment library in the content server. If you move or make a copy of a fragment, all of its assets are included.
You can add, edit, and remove fragment assets in the Fragment Assets dialog in the Fragment Editor.
13.12.5.1 Adding an Asset
To add an asset, perform these tasks:
-
With the fragment open in the Fragment Editor, click Assets.
This opens the Fragment Assets dialog (see Section A.59, "Fragment Assets Dialog").
-
To create a subfolder for the asset (this is optional), click Add Folder, type a name for the folder, and then press Enter on your keyboard.
By default, Site Studio creates an asset folder based on the fragment's ID (see Section 13.12.2, "Specifying Fragment Properties"). The folder name uses all lowercase letters to ensure that the fragment works on all platforms (specifically, UNIX). If you create any subfolders, you should use all lowercase letters as well. In addition, you should use only ASCII characters (see note below).
-
Highlight the folder that you would like to add the asset to and then click Add Asset (the root, or top-level folder, is the default location for assets).
-
Browse to the file on your file system and then click Open in the Windows dialog.
-
Click OK to close the Fragment Assets dialog and return to the Fragment Editor.
When you save your fragment, the asset is packaged with the fragment and stored in the fragment library on the content server. You can now refer to the asset from each snippet in the fragment.
13.12.5.2 Editing an Asset
To edit an asset, perform these tasks:
-
With the fragment open in the Fragment Editor, click Assets.
-
In the Fragment Assets dialog, select the asset and then click Edit to open the two edit options.
-
Click Edit to open the asset in the default application associated with that file type (for example, a cascading style sheet may open in Notepad).
-
Click Edit with to open the Edit With dialog where you can use a different application to edit the file.
-
-
Make your changes to the asset and then close the application used to edit the asset.
-
Click OK to close the Fragment Assets dialog and return to the Fragment Editor.
13.12.5.3 Deleting an Asset
To delete an asset, perform these tasks:
-
With the fragment open in the Fragment Editor, click Assets.
-
In the Fragment Assets dialog, select the asset and then click Delete.
-
Click OK to close the Fragment Assets dialog and return to the Fragment Editor.
Only ASCII characters should be used for fragment IDs and the names of asset files and folders. This is because the folder within the zip file, which is created automatically for the assets, is named after the fragment ID, and the zip format does not support extended characters. This is true also for the names of any folders used for the assets and for the names of the asset files themselves.
Rather than edit a cascading style sheet (CSS) asset that is included in a fragment, you can just as well change the CSS declarations in the fragment snippet to reference your own cascading style sheet.
We recommend that you use the same name for your text-based assets (cascading style sheets, JavaScript files, and so on) as you are using for the fragment ID (see Section 13.12.2, "Specifying Fragment Properties"). For example, if the fragment ID is "myfragment," then you should use the names "myfragment.css," "myfragment.js," and so on. Not only does this help you easily identify the files associated with a fragment, but if you ever create a fragment based on this one (using the "Copy and Edit" feature), all of the assets and code within them are updated to reflect the fragment name. As such, the assets seamlessly work with the fragment.
13.12.6 Adding, Editing, and Deleting Fragment Parameters
Parameters are a set of attributes that govern the appearance and behavior of a fragment when it is added to a template. When a fragment contains parameters, you are prompted to enter information in the Fragment Parameter Values dialog before adding the fragment to a template. Parameters can be used to add such things as text, color, size, or a query in the content server. And you can change the value of the parameters each time you add the fragment to a template.
While parameters are optional when building a fragment, they are very useful to make a fragment customizable and reusable. You can add most of a fragment's functionality to the source of the fragment, or you can add it as a parameter that can be changed when the fragment is actually used.
When parameters are used, you can have several renditions of the same fragment on the same template, where different parameters are used in each instance. Moreover, parameters can be useful for developers who have written code for the web site and would like to hand off that code as a packaged feature (a customizable fragment) to a site designer. (This scenario assumes there are multiple users in Designer.)
13.12.6.1 Editing the Parameter in a Fragment
To edit the parameter in a fragment, perform these tasks:
-
With the fragment open in the Fragment Editor, click Parameters.
-
In the Fragment Parameters dialog (see Section A.58, "Properties for Fragment Dialog"), select a parameter in the Name list.
-
Make the appropriate changes to the Type, Description, Default Value, Query Text, and Option List (Query Text and Option List do not apply to all parameter types). For more information, see Section A.58, "Properties for Fragment Dialog."
-
Click the Parameter Up icon (Figure 13-16) or the Parameter Down icon (Figure 13-17) to move the parameter up or down in the list (this also affects its location in the Fragment Parameter Values dialog).
-
Click OK to close the Fragment Parameters dialog.
To see a description of the parameters in the sample fragments, see Appendix C, "Sample Fragments."
13.12.6.2 Adding a New Parameter to a Fragment
To add a parameter to a fragment, perform these tasks:
-
With the fragment open in the Fragment Editor, click Parameters.
-
In the Fragment Parameters dialog (see Section A.58, "Properties for Fragment Dialog"), click the New Parameter icon (Figure 13-18) and type a name for the parameter in the text box provided.
-
Choose a type from the Type menu (for a description of each type, see Section A.61, "Fragment Parameters Dialog").
-
Enter a description in the Description field.
The description displays at the bottom of the Fragment Parameter Values dialog when you use the fragment.
-
Enter a value for the Default Value.
This value is used if you do not choose a parameter value (in the Fragment Parameter Values dialog) when adding the fragment to a template.
-
Enter a value for Query Text and Option List (this applies only to parameters of type "text," "manageddoc," and "managedurl").
-
Click the Parameter Up icon (Figure 13-20) or the Parameter Down icon (Figure 13-21) to move the parameter up or down in the list (this also affects its location in the Fragment Parameter Values dialog).
-
Click OK to close the Fragment Parameters dialog.
13.12.6.3 Inserting Parameters and Parameter Declarations in a Snippet
After you create one or more parameters in the Fragment Parameters dialog, you can insert those parameters into the individual snippets in the fragment (for more information on snippets, see Section 13.12.4, "Adding, Editing, and Deleting Fragment Snippets").
The Fragment Editor includes a convenient option to insert parameters and parameter declarations directly into your snippet code. To insert them, simply place your cursor in the code where you would like to add the parameter or parameter declaration, right-click, and then choose the appropriate action.
A good way to learn how to create and use parameters is to open a sample fragment from the Toolbox and see how its parameters are used. For a description of these fragments and their parameters, see Appendix C, "Sample Fragments."
13.12.7 Adding, Editing, and Deleting Fragment Elements
Elements are areas in a contribution region that can be edited using the Contributor application. These elements appear as fields in Contributor, where users (contributors) can edit text, graphics, and other content.
The most common use of an element is to first create a contribution region on a page template, and then add one or more elements (WYSIWYG, plain text, image, or custom) to that region. Contributors can then open the web page containing the region and add and edit the text or graphics in each field.
A more advanced use of an element is to include it in a fragment to create a static list. A static list bundles multiple elements in a table-like layout that allows contributors to add, edit, delete, and even rearrange rows and columns of elements (see Section C.3, "Static List Fragments").
13.12.7.1 Adding an Element to a Fragment
To add an element to a fragment, perform these tasks:
-
With the fragment open in the Fragment Editor, click Elements.
This opens the Fragments Elements dialog (see Section A.60, "Fragment Elements Dialog").
-
Click the type of element to add to the fragment: WYSIWYG, plain text, image, or custom.
-
In the Element dialog, follow the same steps as if you were adding the element to a contribution region.
-
Click OK to close the Element dialog and then OK again to close the Fragment Elements dialog.
13.12.7.2 Editing an Element in a Fragment
To edit an element in a fragment, perform these tasks:
-
With the fragment open in the Fragment Editor, click Elements.
-
In the Fragment Elements dialog (see Section A.60, "Fragment Elements Dialog"), select the desired element and then click Edit.
-
In the Element dialog, follow the same steps as if you were editing an element in a contribution region.
-
Click OK to close the Element dialog and then OK again to close the Fragment Elements dialog.
13.12.7.3 Deleting an Element in a Fragment
To delete an element in a fragment, perform these tasks:
-
With the fragment open in the Fragment Editor, click Elements.
-
In the Fragments Element dialog (see Section A.60, "Fragment Elements Dialog"), select the desired element and then click Delete.
-
Click OK to close the Fragment Elements dialog.
The Elements button only displays in the Fragment Editor when the fragment is of the type "staticlist" (see Section 13.12.2, "Specifying Fragment Properties").
The Fragment Elements dialog contains an Advanced button. This opens a text editor that you can use to customize your element even more. However, when you start editing an element this way, you cannot return to the Fragment Elements dialog graphical user interface because there is no interface support for these edits.
Static list fragments are designed for use with the Contributor application. As such, when you add the static list to a page template, you must add it to a contribution region and then assign a data file to that region.
13.13 Fragment Libraries
A fragment is a container for code (HTML, XML, JavaScript, Idoc Script, and optionally JSP or ASP), files referenced by that code (graphics, CSS, and additional scripts), and parameters that govern how that code is added to a template.
A fragment library is a container for one or more fragments, and it is how Site Studio stores and manages fragments.
You work with fragment libraries in the following ways:
13.13.1 About Fragment Libraries
Fragments are stored in fragment libraries. A fragment library is stored in the content server as a managed content item.
The library comprises two parts: an XML file and a zip file. The XML file describes every fragment in the library, and the zip file holds all of the fragment assets referenced by each fragment in the library.
In the content server, the XML file serves as the alternate file (the Web Location), and the zip file serves as the native file. If you were to search for the fragment library "SS_Fragments_Examples" (a library included with Site Studio), you would see the following on the content information page:
| Metadata | Assigned values |
|---|---|
| Content ID: | SS_Fragments_Examples |
| Title: | SS_Fragments_Examples |
| WebsiteObjectType: | Fragment |
| Web Location: | HTTP://<Site>/groups/public/documents/adacct/ ss_fragments_examples.xml |
| Native File: | SS_Fragments_Examples.zip |
The default fragments that ship with Site Studio are stored in the following fragment libraries:
13.13.2 Saving a Fragment in a Fragment Library
When you save a fragment that you've created with the Fragment Editor, you must choose a fragment library to store the fragment in. You can store the fragment in its own library, or you can store it, along with several others, in the same library. You are prompted for this the first time you save the fragment.
To save a fragment in a fragment library, perform these tasks:
-
When finished making changes to a fragment (see Section 13.8, "Editing Fragments"), click the Save icon (Figure 13-29) on the Designer toolbar (or click File then select Save).
The Save Fragment dialog (see Section A.67, "Save Fragment Dialog") opens.
-
Click New to create a library for this fragment.
Or, if you have created a library, select it in the list and then click OK.
-
On the Assign Info Form, enter the appropriate metadata for the library (Content ID, Type, Title, and so on) and then click Assign Info.
The library is created in the content server, and it displays in the Save Fragment dialog (preceded with the text "server:") the next time you open it.
Note:
The Save Fragment dialog opens only the first time you save a fragment. You're taken directly to the Assign Info Form with each subsequent save.As you create and manage fragments, you may find it easier to group related fragments in relatively small numbers (or in some cases put a single fragment in a library by itself) because fragments cannot be moved around, backed up, or distributed individually. They are handled and managed as fragment libraries (see Section 13.13.4, "Uploading and Downloading Fragment Libraries").
The default fragments that ship with Site Studio are stored in read-only fragment libraries, which is why you don't see them in the Save Fragment dialog (and also why you cannot edit the individual fragments).
You can make your own fragment libraries read-only to prevent others from accidentally overwriting or erasing a fragment (see Section 13.13.3, "Making a Fragment Library Read-Only").
13.13.3 Making a Fragment Library Read-Only
Making a fragment library read-only can be very useful, especially if you're working with multiple designers in the same organization. The sample fragments that come with Site Studio are all stored in read-only fragment libraries to prevent accidental erasure or overwriting.
By making your fragment library read-only:
-
The fragments in the fragment library cannot be overwritten or deleted by others (they can only be copied and edited).
-
The fragment libraries won't appear in the Save Fragment dialog, which prevents others from adding fragments to that library.
To make a fragment read-only, perform these tasks:
-
Log onto the content server and search for the fragment library.
-
Open the Content Information Page for the fragment library.
-
Right-click the Web Location file (with the .xml file extension), choose Save Target As, and save it to your system.
-
Check the fragment library out of the content server and download the native file (with the .zip extension).
-
Open the .xml file in a text editor and add the text readonly="true" to the root element <fragments> tag. The resulting tag should look like this:
<fragments name="SS_Fragments" readonly="true">
-
Save and close the file and then check both files back into the content server, specifying the .zip file as the Primary File and the .xml file as the Alternate File.
It may be necessary to refresh the Toolbox in Designer to see the read-only fragments.
As an alternative to these steps, you could also use Designer's Download Fragment Library feature, extract the .xml file out of the downloaded zip, re-archive the zip, and use Designer's Upload Fragment Library feature to return the library to the content server (see Section 13.13.4, "Uploading and Downloading Fragment Libraries").
13.13.4 Uploading and Downloading Fragment Libraries
After you create and edit a fragment or collection of fragments, you can move the fragment library (which the fragments are stored in) from one content server to another. This can be especially useful if you're working with other designers or developers and want to share fragments with them. Or, perhaps you simply want to create a backup of your fragment library for safekeeping.
To do this, you use the Download Fragment Library and Upload Fragment Library feature in Designer.
13.13.4.1 Downloading a Fragment Library
When you download a fragment library, Site Studio places the library (currently located in the content server) in a single zip file and downloads it onto your system. You can then easily transport the zip file.
To download a fragment library from the server, perform these tasks:
-
Click File then Fragments, then select Download Fragment Library.
-
In the Oracle Content Server Dialog, click Select beside the fragment library to download.
-
In the Windows Save As dialog, browse to a location on your file system and then click Save.
13.13.4.2 Uploading a Fragment Library
When you upload a fragment library (after downloading it following the previous steps), Site Studio checks the zip file into the content server and extract its contents to the appropriate directory (\weblayout\fragments\) where it can be used by the web site.
To upload a fragment to the server, perform these tasks:
-
Click File then Fragments, then select Upload Fragment Library.
-
In the Windows Open dialog, browse to the fragment library (zip file) on your file system and then click Open.
-
On the Assign Info Form, enter a Content ID, Type, and Title for the fragment library.
Note:
Do not alter the WebsiteObjectType metadata. It must be set to "Fragment" to be recognized by your web site. -
Click Assign Info to close the Oracle Content Server Dialog and return to Designer.
Instead of using the Upload Fragment Library feature in Designer, you can also check the fragment library into the content server directly and then use the Site Studio Administration page to deploy the fragment library to the required location. For more information on Fragment Library deployment, see the Oracle WebCenter Content Administrator and Manager's Guide for Site Studio.