Account UI *

This section is being superceded in version 3.

When you create a new account, you can set up a new theme and UI for it. There are no specific rules about this, but this section contains a step-by-step guide for creating a typical UI.

Set up the account UI after you have set up the account (see previous section).

The instructions below presume that you are a provider setting up the account UI for a client.

UI setup involves a hotch-potch of Metrici version 1 and version 2 capabilities, and is not very elegant. It requires that you have access to the client's primary account, the provider account, and to the global admin account.

Create theme package

The theme package contains all the UI components used by the theme, such as the footer text and any custom CSS.

The theme package can be anywhere, but if you are setting up a theme for a client it is best if this is set up within the account of the provider, so that you can continue to support the UI and so that the client is not exposed to the details of the UI. (If you want to give the client control over these parts of the UI, put them in the account public area, see below.)

As the provider, create a suitable theme package within your account. This is likely to me something like provider.clients.client.theme, e.g. metrici.clients.acme.theme.

As the global admin user (i.e. "admin"), grant public package read all and package use draft permissions over the theme package. See [[permissions]] for instructions.

Inside the theme package, create the following nodes:

  • A node with local reference footer, of type library.core.ConstantType, which will contain the page footer. Add a suitable placeholder footer to the description.
  • A node with local reference custom_css of type library.file.ContentFileType. Give it an extension of css, and add a suitable placeholder as the file content (e.g. /* CSS for client */).

Also upload any images and other resources required by the theme, using type library.file.UserFileType.

Create UI specification file

The UI specification file is an XML file which describes the UI required for the theme. At its simplest, you want to add the client's name and identify the CSS and footer for the theme.

Create an XML file called default_ui.xml with the following content, replacing ACME with the name of the client, acme with the client's account reference, and metrici with the high level package of the provider.

<UserInterface>
  <extends>default</extends>
  <Constant>
    <name>applicationName</name>
    <value>ACME</value>
  </Constant>
  <Constant>
    <name>themeHeaderInsert_acme</name>
    <value>
      ${themeHeaderInsertDefault}
      &lt;link rel="STYLESHEET" href="${dollar}{rootPath}metrici/clients/acme/theme/custom_css.css" type="text/css" /&gt;
    </value>
  </Constant>
  <Property>
    <name>themeHeaderInsert</name>
    <value>${themeHeaderInsert_acme}</value>
  </Property>
  <Page>
    <pageReference>footer</pageReference>
    <WidgetList>
      <Widget>
        <widgetName>node_description.jsp</widgetName>
        <nodeVersionReference>metrici.clients.acme.theme.footer</nodeVersionReference>
      </Widget>
    </WidgetList>
  </Page>
</UserInterface>

In English, this specification file means "Create a UI based on the default UI, call the application ACME, add the custom_css.css stylesheet to the end of the header, and use the given footer as the source of the footer".

You can add more CSS and JavaScript files to the header, using a similar syntax to the custom CSS. Remember that all CSS and JS file names uploaded to the theme area must be unique excluding their extension, i.e. you can not have custom.css and custom.js, you must have custom_css.css and custom_js.js.

As the global admin user (or another user with maintain filestore permission), use the file store functionality to upload this file into filestore://theme/acme/default_ui.xml, replacing acme with the client account reference.

Create theme load file and load theme

The UI specification file tells Metrici how to structure the UI, but it does not define the theme. To define a theme, you must load records into the properties table. To do this, you must have submit service authority, i.e. be the global admin user.

Create an XML file called theme_load.xml with content such as the following, replacing ACME and acme as before.

<Database>
  <Property>
    <objectType>theme</objectType>
    <objectReference>acme</objectReference>
    <propertyName>themeName</propertyName>
    <propertyValue>ACME</propertyValue>
  </Property>
  <Property>
    <objectType>theme</objectType>
    <objectReference>acme</objectReference>
    <propertyName>themePermittedUserGroups</propertyName>
    <propertyValue>acme acme-users</propertyValue>
  </Property>
</Database>

The the <propertyValue> element in the second <Property> lists user groups who should be offered the theme. You can add other user groups in here (such as yourself) to test the theme.

Upload the load file to the filestore, as with the UI specification, using a file name of theme_load.xml.

As the global admin user (or another user with submit service permission), paste the contents of the file into the Submit service page, making sure that you uncheck the Add user id and password option, and click on Submit. Check that you get a 0 return code.

(You will be able to access the submit service page even if you do not have submit service permission, but the load will fail. Submit service permission means "run any service"; normal users can only run services that are safe.)

Create account public area

Sign on as the client primary user (e.g. "acme") and create a package called public within the client's account, e.g. acme.public. This can use any suitable package type, such as library.aggregator.PackageType or library.parts.SampleTablePackageType.

Within this public area, create a welcome page that users will see before they are signed on, with a local reference of home, e.g. acme.public.home. Use type library.core.PageType. Create some suitable placeholder text. Create further pages and load other content as necessary, using library.core.PageType for the pages and library.file.UserFileType to upload content.

As the global admin user, grant public package read all and package use draft permissions over the public area. See [[permissions]] for instructions.

If you do not want the client to be able to modify their public content, put the home page in the theme area (see above).

Create domain

Using the domain name management features of your domain name provider, create a subdomain for the client, e.g. acme.metrici.com.

As the global admin user, create a new node of type Domain (library.domain.DomainType) within the domains package, e.g. as domains.acme.

  • Set the name the same as the client name.
  • Give the domain a suitable description, such as "Domain for ACME."
  • Set the signed off home node to the home node in the client's public area, e.g. acme.public.home.
  • Leave the signed on home node blank.
  • Set the theme reference to the reference for the theme, e.g. acme.

Edit the domains package itself to relate the domain name (e.g. acme.metrici.com) to the domain node (from the drop down list). If the domain name is not yet setup, use a suitable pre-defined test one such as test.metrici.com.

Test the account UI

Sign off and enter the client's domain name in a browser (e.g. acme.metrici.com). You should be taken to the client's welcome page.

Check that the footer is as you entered, and the application name (in the browser bar or tab) shows the client name. Check that any CSS you have set up is active.

Sign on as the client's primary user. Check that this brings you to the root of the client account as normal.

Once the account UI is working, you can set up the CSS, footer and welcome pages as necessary.