To detail the capabilities and options within Kinetic Request to create well designed and styled service catalogs.
A Few Tips
- Reuse css with classes
- When the same styles are used on multiple elements, use classes
- Implement exceptions on target elements
- Don’t code multiple classes for one exception, add one class or id specific css style to implement the exception
- Be style smart and flexible
- Don’t try to implement styles that add complexity.
- ex. If a <br/> is feasible and easier than styling vertical centering for all browsers, use the <br/>.
- Check all browsers for compatibility
- Not all browsers compute css the same way.
- In fact, many browsers apply styles differently or add styles that others do not.
- Familiarity with HTML and CSS is important when designing your catalog. For educational or assisting purposes I suggest visiting http://www.w3schools.com/
- 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/
- 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/
- To see existing themes or to learn more about automatically applied styles and theme coloring, see our Theme guides at http://community.kineticdata.com
- 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
Service Item Page Elements
Each service item can have numerous Pages, Sections, Text items, Image items and Questions.
Defines a new HTML page
Defines a section within the page. This is a div element that gets the “templateSection” css class.
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.
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.
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
<div class="questionAnswer preRequiredAnswer preRequiredAnswer_text">
<input class="answerValue answerText preRequiredInput
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.
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:
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
Declares styles that will be applied to any element made using that tag. Example selector: a
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.
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 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.
Choose the appropriate selector. The styles you then define will be applied to only the applicable HTML elements specified.
The styling will apply to all sub elements within the Question element.
Declares styling that will only apply on the labels of the answer sub elements.
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.
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:
alert("Custom js here!");
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:
An author can go one step beyond custom CSS or referenced CSS or JS files by utilizing the Theme structure of Kinetic Request
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.
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:
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.
The JSP that will be displayed as a confirmation.
This JSP is the base or commonly referenced from a service item.
This JSP is used within an iframe for a display/review of a request.
This JSP is used as a display, non-editable review of a request in the system.
This JSP is used as a catalog main view, often a launcher service item.
This JSP is used as a home view for a catalog, often a launcher service item.
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.
This JSP is used to populate a list of service item categories and service items.
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.
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.
All images should be contained in this folder. Some images do go in the yui-skin within css as a special case.
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.
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.
Includes the YUI package JS and CSS. The debugjs parameter has not been implemented to affect the included files here.
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.
Contains core and extended catalog functionality for display purposes as well as data handling for Kinetic Request objects.
Used for service item look up and error handling functionality.
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.
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.
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.