Administration-Customizing

From Pnet-Community

Jump to: navigation, search

Contents

[edit] Customization and Branding Strategies

Before beginning, make sure you have read the Overview of Customizing Project.net.


[edit] Create a configuration for your installation

Project.net contains many of its settings in configuration tokens; these tokens are stored in named configuration sets. For example, if you want your company’s name and logo to appear on the Project.net login page, you would change the values of two specific tokens.

While you can alter the Project.net default configuration set, it is recommended that you create a configuration just for your installation. Project.net will first use the values from your configuration. Any values not set in your configuration will receive their values from the system default configuration. Using a separate configuration isolates your custom settings, making them more obvious. More importantly, alternate configurations are preserved whenever the Project.net software is upgraded, while the default configuration loses any changes.

Note: Project.net can have more than one active configuration. Which configuration is selected for a user is determined by the URL or IP address he or she used to access the Project.net server. For example, users accessing the server through projects.mycompany.com may see the results of the default configuration, while those using custom-projects.mycompany.com could see a site customized by an alternate configuration.


Note: It is possible to "dump" the configuration tokens in the form of a script that can be applied to another database, "loading" those tokens into the second database. To extract the tokens, modify and run the script: /trunk/core/db/oracle/create-scripts/tools/ generate_update_system_properties_dml.sqlto. Run the resulting script against another Project.net database to set those tokens in the second database.

[edit] Create a custom configuration

Follow these steps to create a installation-specific configuration

[edit] Instructions

  1. From within the Application Administration interface, chose Manage / Configurations.
  2. Click the Create icon to create a new configuration.
  3. Enter:
    1. Name - Suggestion: use Standard Production Configuration or use the value used for the siteHost token.
    2. Description - Suggestion: include the siteHost value as part of the description.
    3. Abbreviation – This will be used as part of the token identifier.
    4. Choose the Default Language. Note, you _must_ select a value.
    5. Select multiple Supported Languages by holding down the Control key while clicking the desired names. You can leave this as the default value.
    6. Supported Host Names (CSV) – The values in this field determine when this configuration set will be used. List the web site names you want associated with configuration, separated by commas. If you enter projects.mycompany.com, login.projects.mycompany.com either address will cause the values in this configuration set to be used, in conjunction with the values from the default configuration.
  4. Submit your changes to create the configuration set.

[edit] Site-specific token values

Follow these steps to create a installation-specific configuration

[edit] Instructions

  1. From within the Application Administration interface, chose Manage / Configurations.
  2. Click on the name of the custom configuration from the list of configurations.
  3. Choose Tokens from the menu on the left.
  4. Select Basic Branding from the Category list.
  5. Click Filter
  6. Set the appropriate values for the tokens below.
  7. If a token does not appear in the list you can enter its name in the Token Name: search field and click the Filter button to locate it.
    prm.global.brand.defaulthost: Same as the default configuration token
    prm.global.brand.defaultjsprooturl: /
    prm.global.brand.defaulttimezone
    prm.global.brand.defaultsitescheme: http://
    prm.global.brand.legal-name
    prm.global.brand.name
    prm.global.login.channel.login.title
    prm.global.brand.logo.login.href - URL used by the image in the page header
    prm.global.default.site.href
    prm.global.footer.copyright.href
    prm.global.footer.poweredby.href
    prm.global.login.requestinformation.text
    prm.global.default.email.fromaddress
    prm.global.help.feedback.emailaddress
    prm.global.help.info.emailaddress
    prm.global.help.legal.emailaddress
    prm.global.help.sales.emailaddress
    prm.global.help.support.emailaddress
  8. Submit your changes. You may not see the results until you login again.

[edit] Troubleshooting a configuration

Once you have established an custom configuration the first thing to verify is that Project.net is using that configuration rather than the default. Here are some hints:

  • In the custom configuration set the token prm.project.login.login_header_text-1 to something like "Alternate Configuration". This will make it easy to determine when this configuration is being used. If you go to the login page and it still says "Member Log in" rather than "Alternate Configuration" then the custom configuration is not being used.
  • Check the hostname values for the custom configuration. List any hostnames that should trigger this configuration. You may want to include 'localhost' or any specific ports. For example, "login.project.net, login.project.net:8080, localhost".
  • Make sure the hostname for the default configuration is blank. Since it is a required field you may have to enter 'bogus-hostname.project.net' as its value. Do not include localhost or any of the hostnames used for the custom configuration.

Note: You do not need to restart the application server after changing a value in any of the configurations, such as a hostname.

[edit] Customizing images

You can replace most of the images used in Project.net through a combination of tokens and the use of a Tomcat Context, which maps a Tomcat "virtual directory" to a physical location in the file system. Alternate or customized images are placed in the virtual directory and their tokens changed to refer to this directory. At runtime Project.net will use the images in the virtual directory, rather than its default image directory. Note, unless you plan to modify the Project.net JSP source pages, the replacement images must be the same size as the originals.

Common images replaced in Project.net

Token Name Description Size(pixels)
pnet_logo2.gif The Project.net logo on the login page 165 x 90
pnet_home_button.gif The Project.net Home image on the login page 113 × 17
prm.global.header.banner.image The Project.net image in the page header 103 x 50

[edit] Pre-requisites

  1. If you have not created one, create a Project.net configuration that will override the default configuration.
  2. Choose a file system location to hold your replacement images (ex. C:\pnet\brand\images, /opt/pnet/brand, etc). It is suggested to create a sub-directory for each Project.net configuration or brand, if you have more than one configuration.
  3. Figure out which image you want to replace and its size, a few of the commonly replaced images are listed above.
    • From within a browser, right-click on the image, select Properties from the pop-up menu. From the properties dialog look at the Address (URL): entry and note the name of the image, which appears at the end of the URL. Also record the size of the image, listed in the Dimension field.
  4. Create a replacement image the same type and size as the original; save it in the file system location chosen above.
  5. Follow the remaining instructions based upon your configuration below.

[edit] Adding Static Resources via a Tomcat Context Resource

If you are using the Tomcat application server you can substitute static resources, such as a custom image, through a Tomcat context. The use of a context enables you to substitute customized images for Project.net's without touching the Project.net EAR file.

[edit] Instructions

  1. The following instructions assume the alternate image is named mycompanyLogo.gif and is stored in a directory named /opt/pnet/branding/. Substitute the directory and filename as appropriate for your system.
  2. Within APACHE_HOME/conf/Catalina/localhost/ create the the following file named pnet-branding.xml
    • The value for docBase is the path to the base directory that will hold the alternate image.
    • Use forward slashes (/) as directory separators in the path name.
    • For Windows systems, you can include a drive designator (e.g. C:/ or D:/) at the beginning of the path.
    <Context
    path="/pnet-branding"
    docBase="/opt/pnet/branding" <----- Substitute path to image directory
    debug="1"
    reloadable="true"
    crossContext="true">
    </Context>
  3. Restart Tomcat.
  4. Login to Project.net as an application administrator.
  5. From within the Application Administration interface, chose Manage / Configurations.
  6. Click on the name of your custom configuration from the list of configurations.
  7. Choose Tokens from the menu on the left.
  8. Search for the token representing the image you want to replace, for example prm.project.login.pnet_logo2 is the token for the logo on the login page.
  9. Change its value to <path value from pnet-branding.xml>/<image file name>. In our example, it would be: /pnet-branding/mycompanyLogo.gif
    • This pathname should start with the last directory listed as docBase in conf-data.xml.
  10. Apply the settings.
  11. Logout of Project.net. You will see your logo in the upper left of the log in page.

[edit] Troubleshooting

  • If you still see the Project.net logo, chances are the default configuration is still being selected over your alternate one.
    • Right-click on the logo and select Properties from the pop-up menu.
    • From the properties dialog look at the Address (URL): entry. If does not have the image file you defined in the prm.project.login.pnet_logo2 token then your configuration is not being selected. Refer to the troubleshooting section of Create a Configuration for Your Installation.
  • If the logo is missing (i.e. an icon with a red X is displayed instead), again look at the image properties to see what image should be displayed. Check for typos in the name.
  • Note, some installations of Tomcat do not need /pnet-branding specified as part of the path in an image token. If the image is not displayed and the image path in the image properties dialog lists /pnet-branding/pnet-branding twice in the path then remove /pnet-branding from the image token's value.
  1. If the name and path are correct, cut-and-paste the image path from the image properties and paste it into a browser, the browser should display the image. If the browser says "Image Not Found" then restart Tomcat and repeat this step.
  2. Note, Tomcat only reads the context directory when it starts. If you add images to this directory once Tomcat is running then you must restart Tomcat in order to display them.
  3. Finally, double-check pnet-branding.xml; do not forget to restart Tomcat after changing this file.

[edit] Adding Static Resources via an Apache Webserver

If you are using the Apache web server you can substitute static resources through the server.

[edit] Instructions

  1. Edit the httpd.conf file (probably /etc/httpd/conf/httpd.conf) and add the following lines at the bottom underneath the rest of our additions:
    <LocationMatch /ext* >
    SetHandler default-handler
    </LocationMatch>
    Alias /ext /home/weblogic/extResources
    <Directory /home/weblogic/extResources >
    Order allow,deny
    Allow from all
    </Directory>
  2. Create a directory /home/weblogic/extResources (the capitalized R is very important, failure to do it correctly will make you irritated later)
  3. Place files that you want to be served in this directory.
  4. The user running httpd (probably apache) will need to have some permissions. It will need to have execute permissions on each directory leading up to the extResources directory. (That is, /home /home/weblogic /home/weblogic/extResources). It will also need to have read on the files you want to show. If you want to create subdirectories inside of extResources, just make sure the apache user has "x" permissions.
  5. Restart your server. Look for the apachectl cmd (probably /usr/sbin/apachectl) and run /usr/sbin/apachectl restart.
  6. Test your files with a web browser (e.g. http://projects.yourcompany.com/ext/images/topnav-banner-bg.gif )

[edit] Customizing page header

You can change both size and content of the header at the top of the page.

  • To change the size, create the following token
    • prm.custom.topmenu.height
    • It should be a text value with header height in pixels
  • To set custom content
    • Create file page.html or page.jsp
    • Create or update token
      • prm.custom.topmenu.content
      • with the text value 'html' or 'jsp'
    • To use the standard header, remove prm.custom.topmenu.content or give it a blank value.

[edit] Customizing page header link

The logo in the page header is a link, by default it points to www.project.net. To define the link for the image in the page header set prm.global.brand.logo.login.href in the non-default configuration. Common links are:

To link to... Use this URL...
Personal Dashboard page https://<hostname>/personal/Main.jsp
Personal Assignments page https://<hostname>/assignments/My?module=160&redirectedFromSpace=true
Portfolio page https://<hostname>/portfolio/Project?module=160&portfolio=true

[edit] Interface customization via CSS

You can customize any CSS file with dynamic values from either an existing or new configuration token.

For example, the following static CSS with a fixed value for left::

file /css/ourcss.css

  div#ourFrame, {
  position: absolute;
  left: 10;
  }

Can have its value contained in the configuration token prm.ourframe.left using this format

  div#ourFrame, {
  position: absolute;
  left: $$prm.ourframe.left$$;
  }

At runtime, $$prm.ourframe.left$$ will be replaced with the database value for the token prm.ourframe.left.

Note: To use this feature you have to add filter mapping for your css file into web.xml for your application server (Tomcat)

  <filter-mapping>
    <filter-name>CSSDbValues</filter-name>
    <url-pattern>/css/ourcss.css</url-pattern>
  </filter-mapping>

You can also define a default value in case the token was not added into database or does not have a value. Default values should be added to filter declaration as init param in the correct web.xml files.

  <filter>
    <filter-name>CSSDbValues</filter-name>
    <filter-class>net.project.css.CSSDbValues</filter-class>
    <init-param>
      <param-name>prm.ourframe.left</param-name>
      <param-value>1o</param-value>
    </init-param>
  </filter>

[edit] Replacing the login screen

  1. Create html (or jsp) page for custom login screen and save it in '/custom'.
  2. Now, add or edit the following token
  • prm.custom.loginscreen.content
  • with text value 'html' or 'jsp'
  • To use the standard login screen, remove prm.custom.loginscreen.content or give it a blank value.

Login screen example:

    <form action="/LoginProcessing.jsp"" method="post">
      <input type="hidden" name="userDomain" value="1000">
      Login: <input type="Text" name="J_USERNAME" size="20" maxlength="32">
      Pass: <input type="Password" name="J_PASSWORD" size="20" maxlength="20"     
      MAXLENGTH="60">
      <input type="submit" name="submit" value="Submit">
   </form>

[edit] More Help

Personal tools