Back to tutorials sectionEdit Introduction
View Component provides views with horizontal code (libraries, plug-ins, etc.) It is the simplest Sider extension to create and in many instances (when you want to use existing JS library) you only need to provide a single XML description file.
View component can hold any file, but in general it consists of JS files to be included with the view. Sometimes component can provide a transformation (XSLT) to generate component-specific code. For example, tree component can generate HTML required to show the tree from thee tree-like document.
For the view to use a view component it needs to reference it (see
View). All JavaScript files will be included in the view header automatically when the view is generated. If you want to use view component transformation in the view transformation you need to reference it when you reference the component (again, see
View).
Edit Location
Each view component follows the same folders structure as other Sider extensions. All view components are located in the
ViewComponents folder. Each view component is located in
viewComponentName/version subfolder.
viewComponentName is unique view component name, and
version is component its version in
x.x.x.x format.
For example, view component
sider version
0.5.0.0 would be located in the
ViewCompenents/sider/0.5.0.0 folder.
Edit Description (viewComponent.xml)
Each view component is described by the
viewComponent.xml file. Sider looks for this file to load each view component. The file provides component ID, name and version. It also provides links to all component files.
When creating a new component follow these steps:
- Create view component folder
- Download viewComponent.xml template to the new folder
- Copy all component files to the folder (if you're going to use existing JavaScript component)
- Open
viewComponent.xml for editing - Set
id attribute to the component GUID - Set
name attribute to the component name - Set
version attribute to the component version - Next you need to add references to all view component files.
includes element contains a collection of file elements. Each file provides href attribute with URL to one component file relative to the folder in which viewComponent.xml is located. You will need to create a separate file element for each file you want to be available for the component. This is tedious work and we're working on a tool to automatically generate file elements. For example to reference ViewCompenents/sider/0.5.0.0/sider.js you use this code.
<file href="sider.js" />
There are several reasons why we require a separate
file element for each file instead of simply parsing view component folder.
- In the future file might be located on a different media, such as database or online, where parsing for all files will be problematic.
- Sider validates view component and ensures all files are accessible for the views that reference this component. If some files aren't, it will disable the view, preventing user from trying to work with unusable views.
- We might add support for the absolute file paths, so that you could reference view component directly from a website (this scenario has potential problems).
At this point view component description is done and you can reference it in your view. You might also want to add custom script files or transformation to assist the view. Remember to keep your view component code as generic as possible, since, potentially any other view can reference it.
Edit Transformation
View component transformation usually generates HTML for the component to function correctly. There can be any number of transformations and view can use any or all of them. The transformation will be included in the view XSLT if
view.xml references the view component XSLT. When that happens, all templates from the transformation will be available for the view. There are some common-sense rules that you should follow when writing transformations:
- XSLT doesn't support namespaces and all templates are in the global scope. Since the view can include any number of view components we should try to take steps to avoid possible name collision. It's a good idea to add a prefix to all global names exposed by the component transformation. You could use "viewComponentName." prefix or "viewComponentName.transformationName." prefix. For example, "sider.tree.createTree" for a template name or "sider.tree.generatingTree" for match template mode.
- Provide named templates for the view templates to call to use template. If you are going to create match template run it in a unique mode.
- Try not to make your work more complicated than it has to be. In all likelihood a view will include only several different view components and name collision will not be a big issue. Still, do take steps to add some uniqueness to your templates and global variables.