• What are some FrameMaker tips?

What are some FrameMaker tips?

Here is a dump of Ed's collected Frame Crib Sheet

How to deal with the spec in general

Launch frame by double clicking on the book. Then open all the chapters.

How to generate the PDF

Update dates. On TitlePage^?.fm update the expert draft version.

Make sure page numbers are updated. File->Edit->Update Book, make sure all boxes are checked.

File->Save as Book. Choose PDF type and location, and accept defaults in setting window, pressing Set on that window.

How To tell FrameMaker to expand or not expand the TOC when generating the PDF.

It's in the Settings window:

How to deal with changebars

How to get rid of them.

Format->Document->Change Bars. Do this for each chapter.

Revision tagging process

When all of the work for a spec revision has been completed, check the work in, tag the workspace, then clear the changebars in all the chapters, and re-check in the files so they're ready for more revisions.

Special character stuff

The character catalog is accessed with the little "f" icon in the upper right hand corner of the inividual MDI window. The Default Font mode is the normal mode. The code mode is for code. The emphasis mode is for italics. Don't use the Italic button.

Special paragraph stuff

The paragraph catalog is like the character catalog, but it's a paragraph symbol that accesses it. Commonly used ones are:

Paragraph is the default

Code Bullet 1 is when quoting the API method and signature

Bullet 1 is a bulletted list.

*Codeline is nice for showing XML code. You have to hit the tab key one more time than you think.

Tables

Like word, but not as nice.

How to do cross references in frame

Make sure the both the source and target documents are loaded into Frame.

Go to where you want to put the "source" of the reference, and usually, you type "please see". Right click and choose "Cross-Reference".

In the "Cross-Reference" dialog, twiddle the "Document:" drop-down to choose the document in which the target resides.

Twiddle the "Source Type" widget to say "Paragraphs"

Twiddle the "Paragraph Tags" option list to choose the paragraph type, say "Head2" to which you want to refer. As you choose different paragraph types, the section headers should show up in the "Paragraphs" list, to the right. Choose the one you want!

Twiddle the "Format" widget to show the right style, usually "SectionNumber&Title".

Press Insert.

Images

If you can re-create those images as PCX files, you can import them in to the document and they should look good.

How do you fix the PDF bookmarks to be correct?

To reorder them:

1. Open the Book file.
2. Open Format->Document->PDF Setup.
3. Shift-click the right arrow button (--->) to remove all tags from the Include Paragraph box.
4. Select the tags listed above click the left arrow button (<---) to move them to the Include Paragraph box.
5. Adjust the bookmark levels according to the list above by selecting the tag and moving them with the << and >> buttons. For example, move the TitleText^? tag all the way to the left by selecting TitleText^? and clicking << until it moves to the far left of the Include Paragraph box. ChapterTitle^? should be one click to the right of TitleText^?. Head1 should be two clicks, and so on.
6. Save the Book file.
7. Generate the PDF.

Conditional Text

How to show/hide conditional text in frame.

Frame doesn't strip it out, but you can show/hide conditional text before you generate the PDF.

1. Open the Conditional Text dialog box by selecting Special>Condition Text....
2. Click Show/Hide.
3. Move Comment and any other conditional text you want hidden to the Hidden column.
4. Click Set.

The Show Condition Indicators checkbox toggles whether conditional text should use colors (on) or be black (off). For instance, the Comment conditional text setting makes the text red and underlined when Show Condition Indicators is checked.

A tip on hiding all conditional text in a book:

1. Follow the above steps to hide the conditional text in one of the chapter files.
2. Open the book file.
3. Select File>Import>Formats.
4. In Import From Document select the chapter file you worked on.
5. Uncheck all the boxes in Import and Update except Conditional Text Settings.
6. Uncheck the boxes in While Updating, Remove.
7. Click Import.

How to add new conditional text

1. Open the Conditional Text dialog box.
2. Type the text you want conditionalized.
3. Select the text.
4. In the Conditional Text dialog box, double click, for instance, Comment from the Not In or As Is column to move it to the In column. This automatically selects the Conditional radio button in Currect Selection Is.
5. Click Apply.

If you are marking an entire paragraph as conditional text, make sure you select the paragraph marker (viewable when you select View>Text Symbols). If you don't, there will be empty lines in the book when you turn off the conditional text.

How to search in conditional text

1. Open the search dialog box (Edit>Find/Change).
2. In the Find field select Conditional Text....
3. Select the Conditional Text setting.
4. Enter the search terms.
5. Click Find.

• My container doesn't support ServletContextListeners defined in TLDs, what listeners are used by the RI?

• My container doesn't support ServletContextListeners defined in TLDs, what listeners are used by the RI? *

• My container doesn't support ServletContextListeners defined in TLDs, what listeners are used by the RI?

• My container doesn't support ServletContextListeners^? defined in TLDs, what listeners are used by the RI? *

• com.sun.faces.config.ConfigureListener (used to parse configuration resources and bootstrap the application)
• com.sun.faces.application.WebappLifecycleListener (used by resource injection)
• com.sun.faces.util.ReflectionUtils$ReflectionUtilsListener (used to init and clear reflection caches)

• I see this error: JSF1033: Resource injection is DISABLED

• I see this error: JSF1033: Resource injection is DISABLED

- This is not necessary if you're using a milestone build of GlassFish UR1 or GlassFish V2. Edit your APPSERV_HOME/domains/<domain-name>/config/default-web.xml and add the following context init parameter:

* Param Name: com.sun.faces.injectionProvider -- Param Value: com.sun.faces.vendor.GlassFishInjectionProvider

<context-param> <param-name>com.sun.faces.injectionProvider</param-name> <param-value>com.sun.faces.vendor.GlassFishInjectionProvider</param-value> </context-param>

- Restart the modified domain.

• What context parameters are available and what do they do?

• What context parameters are available and what do they do? *

The following context parameters are supported the reference implementation and are specific to that implementation. Thanks to Adrian Mitev for compiling this table.

General JSF-related questions

• How do I write a JSF component?

General JSF-related questions

• How do I write a JSF component?

• How do I update JSF implementation in the Java EE SDK (or glassfish) with an updated version?

• How do I update the JSF implementation in the Java EE SDK (or glassfish) with the most recent version?

The JSF Team has a new, experimental, download offering in its Documents and Files section that will overlay the latest JSF nightly onto a given glassfish install directory. Please visit the nightly build section of the JSF Documents and Files project and download the jsf-glassfish-updater.jar. This file contains the latest JSF nightly and can be executed as follows to install it into glassfish.

java -jar jsf-glassfish-updater.jar <PATH_TO_YOUR_GLASSFISH_INSTALL_DIRECTORY>

Where PATH_TO_YOUR_GLASSFISH_INSTALL_DIRECTORY is the parent of the lib, bin, domains (and so on) directories.

The jsf-glassfish-updater.jar file will be updated nightly with the latest JSF nightly build, and is a great way to get the latest JSF in cases where there is no available Glassfish build with the bug-fix you need, or you just don't want to download a whole new Glassfish.

• How do I become a committer?

Follow the instructions in How do I prepare a change bundle? for quick acceptance of your patch. If your patch doesn't include a test case, we would have to create or update an existing test for it which would delay the acceptance of your patch. If you are unable to do so, you can do the following:

1. Make sure you are making changes in the most recent version of the sources.
2. From the javaserverfaces-sources directory, run the command:

   cvs diff -u > somefilename.diff

   cvs update -d -P > somefilename.log

3. somefilename.log lists all the files you modified. Describe the changes you made to each file providing as much detail as possible. This makes it easy for developers reviewing and committing your patch.
4. Send your patch to dev@javaserverfaces.dev.java.net with issue id (if there is one) and a brief summary of the fix/feature as the subject.

   The developer responsible for the section of code affected should either apply the patch and mark the issue FIXED; or add a comment with an objection if the patch does not seem safe, does not appear to fix the problem, or there is not really a problem to begin with. Developers must also confirm that the contributor has filled in and submitted a JCA before commiting their patch.

Notifications of any changes to Issue Tracking, as well as CVS checkins, are automatically sent to the appropriate bug and CVS mailing lists, so you can monitor if the patch has really been applied. Make sure you subscribe to at least the CVS and bug mailing lists for the module you are working on - see the mailing lists page for details.

• How do I become a committer?

Follow How can I contribute? and start contributing enough solid patches that get accepted into the codebase so that we can get a feel for the quality of your code. Contributors who give frequent and valuable contributions will be nominated for "developer" role if they desire. We would appreciate if commiters could abide by the code review and [[#RunTests][test driven development] process we use.

If you think this process is too onerous, please send your comments to project owner.

1. cd to the top level of your workarea.

1. ant
2. 'ant test' on jsf-api and 'ant test' on jsf-ri

• What is the code checkin procedure?

• How do I prepare a change bundle?

• Bundle?

• Changebundle?

• How do I prepare a change bundle?

JavaServer

• What is the code checkin procedure?

• How do I prepare a change bundle?

• How do I prepare a change bundle?

The JavaServer Faces team practices Test First Design. All code checked in must be accompanied by a new automated testcase that exercises that code, or changes to an existing automated testcase that exercises the code. When writing your code, you have the choice of whether a unit test or a system test would be more appropriate to verify the correctness of your code. Unit tests <<<<<<< faq.html live in the jsf-ri/test directory, and system tests live in the jsf-ri/systest directory.

• What is the code checkin procedure?

• What is the code checkin procedure?

1. As a general note, please turn off any auto-formatting in your IDE to keep your diffs to a minimum. Encountering lots of semantically meaningless changes in the version history of a file, mixed in with semantically meaningfull ones, is very confusing. If you must make formatting changes, do so in a separate change-bundle.

   BEFORE CHECKIN, each significant code change to the repository is described in a "change bundle" and sent to dev@javaserverfaces.dev.java.net for review by module owners. If the change-bundle is to fix a bug, the change-bundle can be posted to the bug (either as an attachment or a comment) and a pointer to the bug can be sent to dev@javaserverfaces.dev.java.net.

   The change bundle should be sent in a way that is easiest for the reviewer to review. Examples of change-bundles can be found here.

   For your convenience, you can simply fill out the change-bundle template, deleting the text in []. Please refer to the issue "id" in the bundle and in the subject of your email.

2. The module owner reviews the change bundle
.
• If the reviewer gives approval, you can check it in as is. Please follow the checkin process. Approval is signified by the reviewer replying to the change bundle mail with r=userid.

  For example: Looks good, r=edburns

• If the reviewer requests revisions, you need to produce another change bundle and seek approval. Repeat until approval is given.

• How can I contribute?

* How can I contribute?

• Your feedback is valuable to us, so join our mailing lists and give input.
• Bug reports are very helpful to developers and a great way to contribute to the project. Use the issue tracker to report a bug. Please be sure to include as much information with your report as possible such as a test case, your platform, version number and steps to reproduce the problem.
• If you like to propose a new feature, file an enhancement issue for it.
• You are welcome to submit a patch for a feature you'd like to see or a bug you'd like to get fixed. All contributers must complete the Joint Copyright Assignment form before contributions can be included in the project. Print, complete, sign and mail or fax the Joint Copyright Assignment form to:

Eric Renaud

JSF/Sun Microsystems

4120 Network Circle, USCA 12-105

Santa Clara, CA 95054 USA

Fax: 408-934-6039

Or, send a scanned version to

Questions pertaining only to Sun's implementation of the JSF 1.2 specification

SocketAttach

• How do I debug a JSF Application using Glassfish/NetBeans 4.1?

*How do I debug a JSF Application using Glassfish/NetBeans 4.1?

1. Start Glassfish in debug mode. To do this, edit GlassFish.home/domains/domain1/config/domain.xml . Look for java-config element. Set "debug-enabled" to "true". Restart the server.
2. Attach

   NetBeans

   debugger. Use the following values for Attach and click on "OK".

Debugger: JDPA Debugger

Connector: SocketAttach^?

Transport: dt_socket

Host:

Port: 9009 (If you modified domain.xml to use a different port, use that port number)

Now, when you deploy and run your JSF application, you should see the debuuger stop at your break points.

• How do I install JUnit so it works with Ant?

• How do I install JUnit so it works with Ant?

Install JUnit 3.8.1 from http://www.junit.org/. Copy the junit.jar into your %ANT_HOME%\lib directory.

• java.util.PropertyPermission set to "read,write" (not just "read")
• permission java.lang.reflect.ReflectPermission "*";

• How do I run the automated unit and system tests using Glassfish?

• How do I run the automated unit and system tests using Glassfish?

Get to the point where you can build the code by following the above steps. Set the required properties in build.properties .

1. On the Mac OS X 10.4 Platform, you need to copy $JAVA_HOME/lib/ext/sunjce_provider.jar to glassfish.home/lib.
2. Run ant test from jsf-api. This will run all API tests.
3. If you have GlassFish running, stop the server. Run ant config.container. This performs the necessary configuration modifications. Restart the server.
4. Run ant test from jsf-ri. This will run all RI tests.
5. For your information: There are four separate suites of tests run when ant test is invoked from jsf-ri and can be invoked using the following targets:
• run.junit.test -> runs a small suite of standalone tests that do not require the container
• run.cactus.test -> runs the cactus-based tests
• run.systest -> runs the system tests (basically end-to-end tests simulating http clients)
• run.systest-per-webapp -> similar to the systests above, but these tests are run in separate web applications to keep the environment clean.

*How do I build the Portlet Integration library and the sample application, portlet-guessNumber ?

Note: Portlet Integration library is based on JSF 1.1.x. So it will not work against the JSF head which is based on JSF 1.2 You can download the Portlet integration library, sources as well as the sample application to deploy to your portal here: https://javaserverfaces.dev.java.net/servlets/ProjectDocumentList?folderID=3389&expandFolder=3389&folderID=1703

If you want to build it yourself, follow the instructions below.

1. Checkout JSF 1.1 branch, JSF_1_1_ROLLING, or use the JSF binaries bundled in Sun Java system Application Server 8.1.x (SJSAS 8.1.x)
2. If you are building from source, build JSF binaries first using the above instructions. If you using SJSAS 8.1.x, just add properties jsf-api.jar and jsf-impl.jar to your build.properties and point them to right location.
3. cd to the jsf-portlet directory.
4. The build environment assumes jsf-portlet to be in the same level as jsf-ri (just like jsf-tools). If not, you have to explicitly set jsf-portlet-dir.
5. To compile the library successfully, you need to download Portlet API jar. Here is the location: http://jcp.org/aboutJava/communityprocess/final/jsr168/index.html.
6. Set up build.properties as outlined in How do I build the code? section. Set portlet-api.home to Portlet API installation directory. Setting pluto.home is optional unless you are planning to deploy your sample application in pluto.
7. Run "ant”. This will build jsf-portlet.jar which will be located under jsf-portlet/portlet-lib/build/lib.
8. If you are deploying in a Servlet 2.3/JSP 1.2 based container, make sure to replace the JSTL 1.1.* jars with JSTL 1.0.x jars. This applies to demo apps as well running in a servlet environment

• How do I build the Portlet Integration library and the sample application, portlet-guessNumber?

• To override jsf-impl.jar, just copy the desired JAR to GLASSFISH.HOME/lib
• To override jsf-api.jar, copy the jsf-api.jar GLASSFISH.HOME/lib and modify GLASSFISH.HOME/domains/domain1/config/domain.xml to add the following to the java-config element: classpath-prefix="${com.sun.aas.installRoot}/lib/jsf-api.jar"

Steps

1. If you are planning on running the unit tests, copy $JUNIT_HOME/junit.jar to your $ANT_HOME/lib directory.
2. Change directory to the location of the checked out source.
3. Copy build.properties.glassfish to build.properties and set the following properties:
   • jsf.build.home - this must be set to the same directory of the checked out source

• How do I access the source tree via CVS?

• What is required to build JSF 1.1.x and JSF 1.2.x?

• When I try to run my application, I see this exception: javax.servlet.ServletException: Cannot find FacesContext How do I fix this?

• Where can I get the source code for Sun's implementations of the JSF specifications?

• How can I turn on logging?

• What is required to build JSF 1.2.x?

• How do I build the code?

• What is required to build JSF 1.1.x and JSF 1.2.x?

• What is required to build JSF 1.1.x and JSF 1.2.x?

o Ant 1.6.5 <http://jakarta.apache.org/ant/>

o Junit 3.8.1 <http://www.junit.org>

o Cactus 1.4.1 (JSF 1.1) <http://jakarta.apache.org/cactus/>

o Cactus 1.7.1 (JSF 1.2) <http://jakarta.apache.org/cactus/>

o HtmlUnit^? 1.8 <http://htmlunit.sourceforge.net/>

o Tag Library Documentation Generator 1.3 <http://taglibrarydoc.dev.java.net>

• What is required to build JSF 1.2.x?

Requirements for JSF 1.2.x:

1. GlassFish (https://glassfish.dev.java.net/ or any JSP2.1/J2EE 5.0 based container
2. J2SE^? 5.0 http://java.sun.com/j2se/1.5.0/index.jsp or later

• What is required to build JSF 1.2.x?

• How do I build the code?

• How do I build the code?

• How do I build the code?

Once you've accepted the license, and we have acknowledged your acceptance, you can access the source code in the javaserverfaces-sources sub-project of this project. Refer to the CVS instructions for details on configuring your CVS client.

• How do I access the source tree via CVS?

• How do I build the code?

* How do I access the source tree via CVS?

This project contains the source code for Sun's Implementation of the JCP JavaServer(TM) Faces Specification. Access to the source code is under the conditions of the Common Development and Distribution License.

• How can I turn on logging?

• How can I turn on logging?

1. Learn which logger you want to turn on. If you look in com.sun.faces.util.Util you find some usefull constants for logging:

   FACES_LOGGER=javax.enterprise.resource.webcontainer.jsf:    It concerns every logger.

   Other logger constants are:

   • RENDERKIT_LOGGER = ".renderkit"
   • TAGLIB_LOGGER= = ".taglib"
   • APPLICATION_LOGGER= = ".application"
   • CONTEXT_LOGGER= = ".context"
   • CONFIG_LOGGER= = ".config"
   • LIFECYCLE_LOGGER= = ".lifecycle"

   If you want to turn on only the logger for render kit, for exmple, the logger is javax.enterprise.resource.webcontainer.jsf.renderkit.

2. Going on with the intent of turning on the logger for render kit, make a logging config file, for example "jsf-log-config", containing only this line:

   javax.enterprise.resource.webcontainer.jsf.renderkit.level=FINEST

3. Edit your domain.xml file:

   Look for a <java-config> element, and add there a <jvm-options>. If you have put the "jsf-log-config" file in "domains/domain1/config/", for example, your jvm-options looks like this:

   <jvm-options>-Djava.util.logging.config.file=${com.sun.aas.instanceRoot}/config/jsf-log-config</jvm-options>

4. Run the appserver The messages will appear in the regular application server log.

Frequently Asked Questions about Sun's JavaServer Faces Implementation

This Wiki page is for questions about Sun's JSF implementation. General FAQs about the JSF Specification are covered in The FAQ for the JSF Specification.

Questions applying to all versions of the implementation

• When I try to run my application, I see this exception: javax.servlet.ServletException: Cannot find FacesContext How do I fix this?
• Where can I get the source code for Sun's implementations of the JSF specifications?

Questions pertaining only to Sun's implementation of the JSF 1.2 specification

Questions pertaining only to Sun's implementation of the JSF 1.1 specification

Questions applying to all versions of the implementation

• When I try to run my application, I see this exception: javax.servlet.ServletException: Cannot find FacesContext How do I fix this?

This is most probably caused by a request going to your server but not being picked up by the FacesServlet. Make sure you have properly mapped the FacesServlet. You need to follow the insructions in Writing the web.xml File and Invoking the FacesServlet in the JavaServer Faces Tutorial.

• Where can I get the source code for Sun's implementations of the JSF specifications?

See this FAQ. These FAQs will be migrated over to this Wiki.

Questions pertaining only to Sun's implementation of the JSF 1.2 specification

Questions pertaining only to Sun's implementation of the JSF 1.1 specification

-- Main.edburns - 11 Apr 2006