Skip to main content
Kinetic Community

Design and Style Guide

Purpose

To detail the capabilities and options within Kinetic Request to create well designed and styled service catalogs.

A Few Tips

  1. Reuse css with classes
    1. When the same styles are used on multiple elements, use classes
  2. Implement exceptions on target elements
    1. Don’t code multiple classes for one exception, add one class or id specific css style to implement the exception
  3. Be style smart and flexible
    1. Don’t try to implement styles that add complexity.
    2. ex.  If a <br/> is feasible and easier than styling vertical centering for all browsers, use the <br/>.
  4. Check all browsers for compatibility
    1. Not all browsers compute css the same way.
    2. In fact, many browsers apply styles differently or add styles that others do not.

Notes

  1. Familiarity with HTML and CSS is important when designing your catalog.  For educational or assisting purposes I suggest visiting http://www.w3schools.com/
  2. A good CSS Cheat Sheet can help you as you define your styles.  W3Schools has helpful css information but  here is a helpful example of a css sheet:  http://www.pxleyes.com/blog/2010/03/most-practical-css-cheat-sheet-yet/
  3. Knowledge of Java and Java Server Pages (JSP) will help design as an author/developer designs JSPs for themes.  Here is a JSP tutorial site:  http://www.jsptut.com/
  4. To see existing themes or to learn more about automatically applied styles and theme coloring, see our Theme guides at http://community.kineticdata.com
  5. Finally, design using a browser with a good Web Developer toolset like Google Chrome or Firefox.  Remember Tip 4, however, and to check all browsers you must support.

Design and Styles

Kinetic Request offers options for design including creating elements directly, styling on those elements or within the service item, as well as including custom css reference or declarations.  You can also reference a design theme with custom JSP pages, css, javascript and other resources like javascript packages.

Service Item Page Elements

Each service item can have numerous Pages, Sections, Text items, Image items and Questions.

Page
Defines a new HTML page

Section
Defines a section within the page.  This is a div element that gets the “templateSection” css class.

Text
Defines a div element that can contain free text, including more HTML if the author chooses to enter such within the KR console.  This element gets the “dynamicTest” css class.

Image
Defines a div element wrapper around an img element.  The div element gets the “imageElementLayer” css class while the img element gets the “imageElement” class.

Question
Each Question element creates a group of nested divs.  Here is an example of a text input question answer pair.  Based on the type of answer, many css classes are generated accordingly.

<div class="questionLayer  preRequiredLayer preRequiredLayer_text">
            <div class="questionLabel preRequiredLabel
              preRequiredLabel_text">LABEL_TEXT</div>
            <div class="questionAnswer preRequiredAnswer preRequiredAnswer_text">
                        <input class="answerValue answerText preRequiredInput
                             preRequiredInput_text" />
            </div>
</div>

Classes Generated by Kinetic Request

Kinetic Request auto applies css classes to the elements the author implements in the service item.  Page 5 details some of these.  When the HTML is generated, these classes are automatically added.

These classes do not have any css styles defined unless the author defines them.  Thus, they will not alter the design or layout unless otherwise implemented to do so.

The classes are applied by rules built into Kinetic Request.  A full list would be exhaustive and unusable, but by building a service item and then using your browser’s web development tools you can find classes that would be usable for your design implementation.

Ex.  “answerText” is a css class applied to any input element of type text.  Thus, any style you want to appear only on those type of inputs could be added by defining answerText with those styles.

Defining Styles within Kinetic Request

The primary way to define styling within Kinetic Request is by declaring it with classes on the styles tab of the service item.

cssStyleTab.jpg

The user can declare three different Style Types.  A Style Selector must then be specified.  The types are detailed below with an example of a selector:

CSS Class
Declares a traditional css class.  Classes should be used when a set of styles need to be applied to multiple elements.  The class is reusable on each element.  Example selector:  catLink

HTML Tag
Declares styles that will be applied to any element made using that tag.  Example selector:  a

Combined
Declares styling that will be applied to a combination of HTML tag and css class.  Example selector:  a.catLink:visited, a.catLink:link

This styling will be specific only to the service item it is declared on.  Thus, if you need to declare an auto-generated css class with different styling for two different service items you will be able to.  If you are looking to define styles, specifically css classes, more broadly across your catalog you will want to use a Theme, detailed later.

Adding Styles to Service Item Elements

Each service item element can have a css class applied.  This will apply the class to the outermost element in the case of those with wrappers/nested elements.

cssElement.jpg

By selecting an element and “Modify” (or double-clicking) you bring up the details window.  On the Style tab you can specify the css style class.  You may also add specific styles to the element.  As these are direct styles defined on the element, they will override class styles due to CSS hierarchy rules.  This is only suggested for specific, exception needs as suggested by Step 2.

Question Elements

Question elements have more opportunity for styling within KR’s author console.  You can apply a css class as normal to the surrounding wrapper div.  When you select “Add” you can define a style for All sub elements, the Question Label, the Answer Label, or the Answer Value(s).

Refer above to see how a question element is generated with HTML and the related elements.

cssQuestionElement.jpg

Choose the appropriate selector.  The styles you then define will be applied to only the applicable HTML elements specified.

All
The styling will apply to all sub elements within the Question element.

Answer Label(s)
Declares styling that will only apply on the labels of the answer sub elements.

Answer Value
Declares styling that will only apply on the element that makes up the answer value sub element.  This could be a radio button, an input field, a textarea field, etc.

Question Label
Declares styling that will apply on the question label sub element, typically a div element containing text.

Custom Header Content

Found on the Advanced tab, the field for custom header content allows an author to add any data a developer might put in the header of a web page.  Some examples include:

Custom Scripts
The author can add javascript directly to the header.  Use the following script tag to js to the custom header content field:

<script type="text/javascript">
function functionName(){
     alert("Custom js here!");
}
</script>

Custom CSS
The author can add custom css directly to the header.  It is preferable to instead add defined css styles using the Styles tab instead.  Use the following style tag to add styles directly to the custom header content field:

<style type="text/css">
styleSelector {styleName:styleValue;}
</style>

File References
The author can reference a css or javascript file, or a js package, from the file system.  This allows an author/developer to create a css file of defined styles that can be referenced on multiple service items to be easily reused.  The same can be said for a javascript file of functions.  The author might also wish to reference a specific javascript package or library for use like jQuery, YUI or another.

advanced tab.jpg

An author can go one step beyond custom CSS or referenced CSS or JS files by utilizing the Theme structure of Kinetic Request

Using Themes

A theme, which might also be considered a skin, is a package of files used to produce the design, layout or style of a site or application.  In this case, a theme can be used to skin a catalog.

Kinetic Request uses a JSP file to produce the basic layout or container of the elements put on the Page tab within a service item.  Design and logic within that JSP alters the layout based on the development.

A theme can contain numerous JSP files, as well as CSS, Javascript, image files, and more.

Referencing a Theme within Kinetic Request

The JSP that a service item references determines what theme is being used for it.  The Display Page (JSP) field on the Advanced tab (see above) is the JSP used to produce the layout in a web browser.  The field references files from the root of the web application.  Thus to access a JSP file within the theme directory you must specify the file with the following relative URL path:

/themes/THEMENAME/JSPFILENAME.jsp

JSP files at the root are base files used by earlier verisons of Request or by base catalog service items.

Java Server Page (JSP)

Each theme has a number of JSPs, which allows a developer to use java programming to build an HTML page.  There is also a "partials" folder which contains JSPs used to building parts of pages or to be referenced by other JSPs.  Below are common JSP files within a theme.

confirmationPage.jsp
The JSP that will be displayed as a confirmation.

displayPage.jsp
This JSP is the base or commonly referenced from a service item.

frameReviewPage.jsp
This JSP is used within an iframe for a display/review of a request.

reviewRequest.jsp
This JSP is used as a display, non-editable review of a request in the system.

serviceCatalog.jsp
This JSP is used as a catalog main view, often a launcher service item.

serviceHome.jsp
This JSP is used as a home view for a catalog, often a launcher service item.

partials/myInfo.jsp
This JSP is a pop up, used when the username from the Welcome box is clicked to get info of the user that is logged in.

partials/serviceItems.jsp
This JSP is used to populate a list of service item categories and service items.

CSS

Each theme has a css folder to contain all css used by the catalog.  The CSS could be that for elements on the JSPs, utilized by javascript to affect the view or used in service items in any way referenced above.  These CSS files are referenced/included in JSPs after the includes (see below), allowing you to overwrite any CSS from the default.

CSS styles defined here are referenced by the JSPs that include them unless directly referenced in the service item.  The service item might reference through an attachment or by putting in a css reference in free text or by adding styles to service elements.  The benefit of using the css in the theme is that it can be referenced in each service item instead of defined on every service item.

YUI-skin
These stylesheets allow a developer to style their YUI elements such as the datatable used for service item status.  Images are also contained within to keep the yui-skin area isolated for ease of augmentation.

For more about styling or restyling a theme built from ACME, please see the ACME CSS Quick Sheet.

Images

All images should be contained in this folder.  Some images do go in the yui-skin within css as a special case.

Includes

The JSP fragments within this folder are designed to be included by many files.  Files the developer wishes to reference in multiple JSPs (or other files) are contained within each fragment.  JSPs then reference these includes to bring in whatever css, js, or special resources may be included.  A developer can create more common includes or adjust as necessary/desired.  This creates a common file to allow easy changes or updates.

Included files should be referenced first in a JSP file.  The existing themes already do this.  This way, non-theme CSS or JS referenced in the CSS folder or JS folder will overwrite any CSS or JS included through these JSP fragment files.  CSS styles implemented on the service item will also overwrite.

kdInclude.jspf
Includes common CSS and JS of the theme as well as CSS and JS from the base Kinetic Request resource.  Also note that a debug parameter can be implemented here to control which files are included like compressed JS normally, otherwise individual JS files.  The debug parameter is a boolean debugjs.

yuiInclude.jspf
Includes the YUI package JS and CSS.  The debugjs parameter has not been implemented to affect the included files here.

custom.jspf
Creating a custom include would most easily allow you to centrally include custom files without having to change a number of JSPs every time the included references have to change.

Javascript

Kinetic Request's deployed resources include custom javascript as well as the YUI 2 javascript package.

catalog.js
Contains core and extended catalog functionality for display purposes as well as data handling for Kinetic Request objects.

service_item.js
Used for service item look up and error handling functionality.

Resources

This folder allows a developer to include custom packages like jQuery, YUI, or any other resources specific to the theme.  References to these packages can be put into individual JSPs or an Include can be created to utilize the resource.

Core Styling

Kinetic Request continues to contain core styling files for backwards capability.  These files include the core JSPs mentioned above as well as various css, js and image resources.

JSPs

Kinetic Request has a number of JSP files it has used to produce a layout before Themes were implemented.  These files exist in the core directory of the application and will not be removed to ensure bakcwards capability.  Using a theme is encouraged to provide a unified layout, while also allowing a company's branding to be implemented.

Resources

The Resources folder of the application root contains resources used by the core application or numerous catalogs.  Core CSS and javascript are contained within subdirectories.  Common image and JS packages are contained within the resources as well.