RpReports Customization

RpReports Customization explains how to create a new project for RpReports .

Customization is performed by modifying four external database files:

Project settings - such as the name of the project and client settings.
Attribute Definitions - define sach attribute, type, whether the user can modify it, and whether it appears on the reports.
Attribute Level Files - define which attributes are visible at each Porject level.
Default Attributes - assign the initial attributes for each component based on component name.

Note:In this article PROJECT refers to the code name of your project. It should not contain any spaces, dots or other special characters (underscore or dash are OK). (e.g. Acme_Furniture). The actual project name, defined in the PROJECT_settings.csv file can contain spaces.

How to proceed

Read through this article to understand the customization files.
Modify and load the RpReports_Demo project stored in the RpReports_Demo folder of the location where you installed RpReports.
Proceed to Setting up a project (below) to create and test your own project.

Beta testers: Be prepared for things to go wrong. Let us know what problems you are having and we will create new versions for testing.

File Names

The three setup files have names which all start with the project name. If your project name was PROJECT, the three files would be called:

PROJECT_settings.csv - project variables and options.
PROJECT_attdef.csv - attribute definitions.
PROJECT_attlevX.csv - attribute definitions for level X.
PROJECT_attributes.csv - default attributes for components.

These files are all stored in the same folder as the PROJECT_settings.csv file.

Project setup and options

The Project setup and options file (PROJECT_settings.csv) is CSV format file which describes certain options in your project.

Tip: Your dictionary_name should contain some unique word or characters to help identify it. For instance call it Acme_Inventory instead of just Inventory to avoid conflicts with our vendor's projects. See each section:

Project_settings.csv file sections

See each section for data definitions and a sample.

[Project] - Project Name
[Levels] - Description of attribute and report levels
[Client] - Items to include on Client toolbar
[Globals] - Settings which are always set.
[GlobalDefaults] - Settings which are only set the first time the Client project is loaded, but which can be overridden by the client.
Sample _settings.csv file

Attribute Definitions

The attribute definitions file is a .CSV (comma separated value) file, PROJECT_attdef.csv which describes the attributes in your project.

For each Attribute, define the following:

Attribute - the name of the attribute in the database
Label - the label for dialog boxes and reports. (If this is blank, the attribute name will be used.)
Type - values: string, int, float, date, time
Decimal - number of decimal places to display for floating point values.
MinWidth - minimum width on reports. Use this field to make some fields, such as Description, longer.
Blank - 0 values display as a blank field if set to y.
Substitutions - Set to 'y' if %w%, %h%, %d% and %name% in the field will be automatically replaced with values from the entity. See Substitutions below.
Calculation - calculation used to define value for field. See Calculations below.
Alignment - left, center, right.
BatchEdit - if set to true, then the user can edit this attribute for one or more selected components with a right click.
Comment - a comment to remind you about the attribute.

The first line must be as follows:

Attribute,Label,Type,Decimal,MinWidth,Blank,Show,Edit,Report,Substitutions,Calculation,Alignment,Comment

If you have a line which starts with #Defaults, then it defines defaults for blank values in subsequent lines. You can have more than one #Defaults line in your file.

Attribute Definitions being edited as a .CSV file in Excel

For help in creating a .CSV file, see: Creating .CSV file from .SKP file names .

Substitutions

In the fields marked for substitution (Substitutions = y), you can enter values which will be replaced by the size of the component. This is done by using special codes, such as %w% in the description.

Substitution codes

%w% is replaced by the width of the component,
%d% is replaced by the depth of the component,
%h% is replaced by the height of the component
%l% is replaced by the longest of width, depth and height. (Useful for long components - like pipe.)
%z% is replaced by the minimum z-height of the component
%v% is replace by the product of width, depth and height (volume)
a-wd - area - width * depth
a-wh - area - width * height
a-dh - area - depth * height
%name% is replaced by the name of the instance or component

Note: The string which receives the substitutions is the value stored on the component.

Sample

This lets you use a generic description for several components, which will be modified by the actual size of the component.

e.g.: "%w% x %d% table" will appear on reports as: 36" x 48 1/2" table

For width, depth, or height substitutions, you can also add an amount, in inches, which you would like to add or subtract from the actual size. e.g. %w-3" will subtract 3" from the width.

Calculations

Fields may be calculates based on values in other fields.

Use %field% to represent the value from another field.
The fields used for calculations must be defined, in previous fields, before the field being calculated. This is because the field being used for calculations may also have calculations.
Floating point numbers must be preceded by a 0. For example, if you want to calculate a 17.5% tax, use a calculation like: %Base Price% * 0.175

Extended prices and costs

To include extended prices or costs in your report:

Add an additional field, e.g. 'Extended Cost. This must come after the cost field being extended.
Set the new field to total
Set the original cost field not to total.
Mark the new field to extend from the original field (multiply the original field by the count)

Attribute Levels

These .CSV files define which attributes appear at each report level.

Ther is a PROJECT_attdefX.csv file for each attribute level.

Show - 'y' to show this attribute on the edit attribute dialog.
Edit - 'y' to allow the user to edit this attribute on the edit attribute dialog.
Selection - 'y' to display this attribute when selecting component.
Report - 'y' to show this attribute on reports.

Default attributes

The default attribute file is a .CSV (comma separated value) file, PROJECT_attributes.csv which describes the default attributes for components in your project.

The first line must contain the names of your attributes. For example:

Component,Manufacturer,Part Number,Description,Cost,Private,Read Only,test bad,Date,Time

If you have a line which starts with #Defaults, then it defines defaults for blank values in subsequent lines. You can have more than one #Defaults line in your file.

Attribute defaults being edited as a .CSV file in Excel

Attribute Defaults viewed as an ASCII text file.

Component,Manufacturer,Part Number,Description,Cost,Private,Read Only,test bad,Date,Time
#Defaults,test_mfgr,,,,,,,,
test1,,pn1,desc1,1.11,private 1,ro 1,test_bad,3/14/2006,
test2,,pn2,desc2,2.22,private 2,ro 2,,,12:00
test3,,pn3,desc3,3.33,,,,,

Special Values for long integers

Excel does not handle long integer values properly - such as 4003982032485, so you must put a less than sign (<) in fron of long integer values so Excel will treat them as a string.

In the .CSV file, use <4003982032485. The < will automatically be stripped off when reporting the attribute value.

Auto Generate Attributes from Component Names

On the RpReports OEM Dialog , there is a function Auto Generate attributes from Component Names.

This creates an empty .CSV spreadsheet with component names which you can use to define your attributes.

See: Auto Generate Attributes

Embed Attributes into Components

You can distributes your project, either with a ..._attributes.csv file to define the attributes, or by embedding the attributes into the .SKP files directly.

On the RpReports OEM Dialog there is a function Embed Attributes into Components

This adds your attributes directly to the .SKP files to define your components.

See: Embed Attributes

Automatic attributes

The description field can be automatically set by the component definition name or the component instance name.

If there are not default values for this field and if the user has not set the values using Edit Attributes, then the values will be obtained from the component instance or the component definition.

You specify which field receives these automatic values by specifying:

description_field_label=field which receives the name of the component definition

in the ini file.

Component naming

The Component field matches the component name up to the first pound (#) sign.

If the user uses Make Unique to create a new version of a component, SketchUp places a # sign in the name. The default attributes for the original component will still apply.
If you have a group of components with the same default attributes - for instance, two components for the same cabinet - one with the door open, one with the door closed - then you can give them names which start out the same up to a # sign and they will share the sale attributes. e.g. if you have two components called:
- 24" cabinet
- 24" cabinet#open

These will both get their attributes from 24" cabinet.

If the user has overridden the instance name, then this will be used instead of the component name.

Setting up a project

Step 1 - Definition files

Create the definition files as above.

Step 2 - Load the Project

Select the menu: Plugins/RpReports/Load RpReports and select your _settings.csv file (e.g. PROJECT_settings.csv)

Step 3 - Verify load

Select the menu: Plugins/RpReports/About RpReports - this should display the name of your project.
Select the menu: Plugins/RpReports/Show Attribute Definitions - this should display your attribute definitions in web browser.
Right click on a component and select Set Attributes... - you should see your attributes.
Set some attributes and create a report.

Status reports

There are some status reports available under the Plugins/RpReports menu to help you debug your project.

Show Component Attributes
This show the attributes for the selected component instance.

Shows all attributes - not just those defined in RpReports
Shows attributes for the component definition as well as attributes for the component instance.
The instance attributes only include settings which are different than the component definition.

Show All Attribute Definitions

Shows the attribute definitions for your project as loaded from the project_attdef.csv definitions file.

Problems

If these steps do not work properly. Load the Ruby Console (Windows/Ruby Console) and reload your project. If any error messages appear send them to Render Plus so we can wee what has gone wrong.

Load a Client Project

See Load a Client Project for information on loading the client project.

Render Plus Software

Simply Realistic 3D Rendering Solutions