Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
359 lines (210 sloc) 13.1 KB

Taglib Description Guidelines

We welcome you to contribute tag descriptions for Liferay Portal's taglibs. Please follow these guidelines as you describe tags in Liferay Portal's .tld files.

Please create an LRDOCS ticket for the description, with API issue type, and be sure to reference the ticket number in any commits you make.

You can commit your changes in a branch based on the master branch of https://github.com/liferay/liferay-portal. Then send a pull request to user liferay, making sure to mention Cody Hoag (GitHub handle: @codyhoag) so he can review your changes. In the pull request description, mention any other version of Liferay Portal you'd like the changes to be ported to.

You must generate the API docs locally to verify the syntax is correct, before sending a pull request.

Scan the rule summaries below or click on them for details:

Rules

Write tag descriptions like a champ, by following these rules!

Accompany every tag library with a description

Example:

<description>Provides the Liferay UI component tags, prefixed with <![CDATA[<code>liferay-ui:</code>]]>.</description>

<short-name>liferay-ui</short-name>

Start All <tag> descriptions with a verb

Example:

<description>Creates a flag icon that lets users report inappropriate content.</description>

<name>flags</name>

...

Include a screenshot of the tag at the end of the tag's description for reference, if applicable

For tags inside of the liferay-portal repo place the screenshot in the liferay-portal/util-taglib/src/META-INF/images/[taglib prefix] folder. Create the folder if it does not currently exist. Include the image in CDATA tags, pointing to the relative path of the image. For tags inside of a module repo, place the screenshot in the module-name/module-name-taglib/src/main/tlddoc/images folder. You will need to create the tlddoc and images directories. The relative path would then be ../images/screenshot.png. The size of the image should be just enough to render the UI element

Liferay Portal Repo Example:

<description>Creates a tabbed UI of section dividers that each house their own content.<![CDATA[<br /><br />Example:<br /> <img src="../images/liferay-ui/tabs.png"/>]]></description>

Module Example:

<description>Hello World <![CDATA[<img src="../images/breadcrumb.png"]]></description>

Punctuate every attribute description (sentence or fragment) with a period

Example:

<attribute>

    <description>The Java class name for any categories added to the entry.</description>

    <name>assetCategoryClassName</name>

    ...

Use complete sentences for all text following a description's initial phrase/sentence

Example:

<attribute>

    <description>Can hold miscellaneous data. This data is not shared with the browser.</description>

    <name>data</name>

    ...

Preferably start <attribute> descriptions using an indefinite article "A" or "An"

Example:

<attribute>

    <description>A name for the form.</description>

    <name>formName</name>

    ...

Only start attribute descriptions with definite article "The", if it's natural and, otherwise, awkward to use "A" or "An"

Example 1:

<attribute>

    <description>The flagged asset's Java class name.</description>

    <name>className</name>

    ...

Example 2:

<attribute>

    <description>The total number of objects in the search container.</description>

    <name>total</name>

    ...

Alternatively start <attribute> descriptions with a noun

Example:

<attribute>

    <description>Text to display next to the flag icon. ...

    <name>message</name>

    ...

Use XML-safe text

Example:

<type>Map&lt;String, Object&gt;</type>

Mark up all code, parameter, tag, and variable references

All references to tag libraries, tags, attributes, and literal values should be marked up as code. You must wrap the markup in a CDATA tag.

Example:

<![CDATA[<code>someValue</code>]]>

Attribute Patterns

You've got tons of attributes, right? Document them, following these patterns.

The name Pattern

Follow this pattern:

<description>A name for the component. [Any additional details]</description>

Example:

<description>A name for the component.</description>

<name>name</name>

The boolean Pattern

Follow this pattern:

<description>Whether to (do something).</description>

<name>disabled</name>

...

<type>boolean</type>

Example:

<description>Whether to disable the input field.</description>

<name>disabled</name>

...

<type>boolean</type>

The param Pattern

Follow this pattern:

<description>A variable name for the component. [Any additional details]</description>

Example:

<description>A variable name for the component.</description>

<name>param</name>

The onClick Pattern

Follow this pattern:

<description>A function to be called on the user clicking the component. [Any additional details]</description>

Example:

<description>A function to be called on the user clicking the component.</description>

<name>onClick</name>

The CssClass Pattern

Follow this pattern:

<description>A CSS class for styling [whateverItStyles].<description>

Example:

<description>A CSS class for styling the icon's URL.</description>

<name>linkCssClass</name>

Tag Types

Curious about specifying attribute types? Follow these tag type guidelines and examples.

Tags that have a Boolean or Integer value must have a <type> tag

Tags that have a String value DO NOT NEED a <type> tag.

Follow this pattern:

<type>boolean</type>

<type>int</type>

Example:

<description>Whether to disable the input field.</description>

    <name>disabled</name>

    <required>false</required>

    <rtexprvalue>true</rtexprvalue>

    <type>boolean</type>

There are special cases where a <type> tag is needed in addition to Booleans and Integers

Java Sets:

<type>java.util.Set</type>

Java Maps:

<type>java.util.Map</type>

Java Formats:

<type>java.text.Format</type>

To be safe, don't specify a <type> tag if you're unsure what type to use.

Deprecated Tags

Have you made a recent update and need to deprecate a tag? Follow these guidelines.

Deprecated tags with a replacement

The deprecated tag should provide a short description that includes the release/version of the initial deprecation, and the name of the tag that has replaced it.

Example:

<description>Deprecated as of 7.0.0, replaced by <![CDATA[<code>liferay-aui:nav-item</code>]]></description>

Deprecated tags with no direct replacement

The deprecated tag should provide a short description that includes the release/version of the initial deprecation, and should state that it has no direct replacement.

Example:

<description>Deprecated as of 7.0.0, with no direct replacement</description>

How to Generate Taglib API Docs Locally

Do you want to generate the taglib API docs locally? Follow these guidelines.

Use the Ant taglibdoc task to build taglib docs for Liferay Portal core tags

Navigate to the liferay-portal/util-taglib directory in the command line and run ant taglibdoc. The docs will be generated in your liferay-portal/api/taglibs directory. Open index.html to view the docs.

Generate taglib docs for Liferay Portal core tags:

ant taglibdoc

Use the Gradle tlddoc task to build taglib docs for modules

Navigate to the liferay-portal/modules/apps/module-name/module-name-taglib directory in the command line and run ../../../../gradlew tlddoc. The docs will be generated in your module-name-taglib/build/docs/tlddoc directory. Open index.html to view the docs.

Generate taglib docs for modules:

../../../../gradlew tlddoc

How to Generate Taglib Jars Locally

So you're trying to jar up your API docs locally. Follow the guidelines below.

Use the Gradle jarTlddoc task to generate jar files for your modules

Navigate to the liferay-portal/modules/apps/module-name/module-name-taglib directory in the command line and run ../../../../gradlew jarTlddoc. The com.liferay.modulename.taglib-version-taglibdoc.jar file will be generated in your liferay-portal/tools/sdk/dist directory, containing the docs information, along with any images you included as well.

Generate jar files for module taglib docs:

../../../../gradlew jarTlddoc
You can’t perform that action at this time.