Lesson 9. Periodic Information Registers
Estimated duration of the lesson is 50 minutes.
- Why We Need the Periodic Information Register Understanding the Information Registers Adding a Periodic Information Register Automatic Filling of Price in a Document when Selecting Products
- Creating a Function Returning a Product Price Calling the Function upon Product Selection and Filling the Price in the Document
During this lesson we will familiarize ourselves with Information Register configurationobjects, or more precisely, with one specific type - a periodic informationregister. You will learn what this configuration object is used for and how itis structured.
We will walk through the creation of one periodicinformation register, which will be used in our configuration, and willdemonstrate how its data can be accessed by means of the 1C:Enterprise script.
Why We Need the Periodic Information Register
We will start by drawing your attention to the Services Rendered document.As you remember, we use that document to select the services that are renderedand then specify the price.
Obviously Jack of All Trades will have a list of services,which will specify the price of each service. It would seem that the price ofservices is an integral part of the services themselves, and should be includedas an attribute of the Productscatalog.
However, a characteristic of the price of services is thatit can change over time. And a situation may arise where we need to makechanges or corrections to one of the previously posted Services Rendered documents. In thissituation we will be unable to get a correct price for the service because thecatalog attribute will store the latest entered value.
Moreover, it is not beyond the realm of possibility thatthe management at Jack of All Trades would want to view the relationshipbetween the company's profit and changes in the price of services rendered. Soit is will be absolutely essential to have the ability to analyze changes inthe price of services over time.
Therefore, to store the price of services, we will use anobject that we have not yet encountered - an Information Register.
Understanding the Information Registers
An InformationRegister configuration object is intended to declare multidimensionalstorage structures for data. Based on an Information Register object, theplatform will create a database table that will store arbitrary informationthat is "bound" to a set of dimensions (fig. 9.1).
Fig. 9.1. An independent periodicinformation register ("Prices") in the Designer and in the Database
The main difference between an information registerand an accumulation register is the fact that every record in an informationregister creates a new resource value, whereas records in an accumulationregister modify the present value of that resource. Because of this difference,an information register can store any type of data (rather than just numeric,as was the case with an accumulation register).
Another important characteristic of an informationregister is its ability to store data in relation to time if required. Thismakes it possible for an information register to store a history of changesover time, rather than just the current data values. If an information registeruses time references, it is referred to as a periodic information register.
The information register's periodicity can be set to one ofthe following values:
- within a second;
- within a day;
- within a month;
- within a quarter;
- within a year;
- within a recorder (if the write mode is set to Subordinate to Recorder).
Periodic information registers will always contain thesystem field named Periodwhich is added automatically. It is of the Date typeand is used to establish the fact that a record belongs to a certain period.When writing data to a register, the platform will always set the value of thisfield to the beginning of the period the data belongs to.
For example, if data is written to an information registerwith periodicity of within a month, and the period for that data is set to4/8/2004, the register will store the data with a period value of exactly4/1/2004.
As with other registers, the system ensures uniqueness ofrecords for an information register. However, while other registers use therecorder and row number as unique identifiers, an information register uses adifferent method to generate its key value.
In this situation, a record key, which uniquely identifies a record, is an aggregate of the register'sdimensions and period (if it is a periodic information register). Aninformation register cannot contain multiple records with identical keys.
If we extend our comparison with an accumulation register,one could say that an information register offers greater freedom in editingthe data it contains. While an information register can be used insubordination to a recorder (where the records of the information register are"bound" to the recording document), an information register can alsobe used independently, wherein the user has total freedom in accessing theregister. An information register that is not subordinate to a recorder isreferred to as an independent informationregister.
For details on the structure of the1C:Enterprise script objects intended to work with the information registers,see "Developer's Quick Reference. InformationRegisters".
Adding a Periodic Information Register
Now we will proceed to creation of a periodic informationregister that will be used to store the retail prices for materials and theprices of services provided by Jack of All Trades.
In the Designer Mode
Open our practice configuration in the Designer and add anew Information Register configuration object.
To do so, highlight the Information Registers branch in theconfiguration object tree and click Add in the configuration window command bar.
In the configuration object editor that opens use theMain tabto enter a name for the register - Prices.
Now set the Periodicity property of this register to Within a second.
This periodicity is selected to be able to trackprices multiple times within a day. But if you have no plans to change pricesso frequently, you can actually select within a day as a value for theproperty.
Here we will also define object presentation in theapplication interface.
Now enter Price for the Record Presentationproperty and ProductPrices forList Presentation (fig. 9.2).
Fig. 9.2. The general properties of the Prices Information Register
Note the Write Mode property. By default the value is Independent, i.e. anindependent information register is created so that in the future we couldenter data into the register manually without using a recorder.
Click Nextand navigate to the Subsystemstab.
The logics of our configuration suggest that this registershould be available in the sections Goods Management, Rendering Services, and Accounting.
So we will check these subsystems in the list (fig. 9.3).
Fig. 9.3. Defining a List of Subsystems where the register will be displayed
Dimensions and Resources
Next switch to the Data tab and create a dimension named Product with a type CatalogRef.Products.
To do so, select the Dimensions branch and click Add in the commandbar of the window.
Indicate that this will be the main dimension (fig. 9.4).
Using the Main property is only reasonable when the dimension is of a typethat links to a database object. Selecting the Main property means that an informationregister record is only meaningful while the object exists with its linkselected as the value of this dimension in this particular record. When theobject is deleted, all information register records related to that object willalso be deleted automatically.
Also since this register dimension has been selected as amain one, a link will appear in the form of Products catalog item (in the Go To group of thenavigation panel). Using this link, you can navigate to the records of thisregister that link to this catalog item in the Product dimension.
Fig. 9.4. Creating a main dimension of the information register
Now create a resource named Price, type Number, length 15, 2 decimal places, non-negative.
To do so, select the Resources branch and click Add in the commandbar of the window (fig. 9.5).
Fig. 9.5. Creating a resource of the information register
In the 1C:Enterprise Mode
Now launch 1C:Enterprise in the debugging mode and reviewthe behavior of our Pricesperiodic information register.
In the 1C:Enterprise window that opens you can see thatnavigation panels in the sections Accounting, Rendering Services, and Goods Management now include the command to open the list of theProduct Pricesregister (fig. 9.6).
Fig. 9.6. Command to open Prices periodic information register
By default the command to open an information register isavailable in the interface of sections where this register is displayed becauseusers should be able to modify data in the registers (unlike the situation withaccumulation registers).
Creating Records in an Information Register
To add a new record to an information register, click New.
Define the prices of services offered by Jack of All Tradesas follows (fig. 9.7).
Define the period retroactively because the period shouldbe equal or prior to the date when a document recording a service rendered iscreated (in our situation it is 7/10/2010).
Next define the retail prices of materials (fig. 9.8).
Fig. 9.7. Prices for services in the Prices information register
Fig. 9.8. Prices for Resources in the Prices Information Register
This provides our program with a very usefulfeature of being able to set prices of services and materials. Given that theprices are stored in relation to the date, we can set new prices in advance andbe certain that the new prices will only be applied on the specified date.
Automatic Filling of Price in a Document when Selecting Products
Our goal is as follows. The Product Prices are nowstored in an independent information register. When we create or modify a ServicesRendereddocument and add some product to the tabular section, we also want the currentprice for this product to be populated automatically with the data from theinformation register in compliance with the document date.
To do so, we need to take two steps.
The first step involves writing some function that willretrieve current price of the product. The second step is calling this functionwhen a product is added to a document and populating the document with productprice retrieved by this function.
Since this feature will hardly be used exclusively in thisspecific document and will be convenient in other documents that containproducts in their tabular sections as well, we will locate this function insome generally available location, i.e. in a common module.
In the Designer Mode
Creating a Function Returning a Product Price
First we will create a RetailPrice()function that will retrieve current retail price of a product and locate thisfunction in a common module of the configuration.
Open the Designer. Under the Common4Common Modulesbranch create a new configuration object Module and name it CatalogFunctions.
You will see that by default the module has Server checked. Itmeans that instances of this module will be compiled only on the server end.
Check ServerCall to be able to call for export procedures and functions of this modulefrom the client end (fig. 9.9).
Populate the module with the following code (listing 9.1).
Listing 9.1. Function RetailPrice()
Function RetailPrice(ActualDate, ProductItem) Export // Create auxiliary object Selection Selection = New Structure("Products", ProductItem); // Get effective register resource values ResourceValues = InformationRegisters.Prices.GetLast(ActualDate,Selection); Return ResourceValues.Price; EndFunction
Now we will discuss this function.
To get the retail price, we will pass two parameters to thefunction:
- ActualDate - a Date type parameter which determines the point in time we want to know the retail price for;
- ProductItem - a link to an item in the Products catalog that we want to get the retail price for.
In the body of the function we will first create anauxiliary object named Selection.
It represents a structure containing the registerdimensions filter. This is the object that we use to declare that we will belooking for register records where the dimension of the Products register is equal to thecatalog item link transferred to the function.
The name of the structure key (Products)should match the name of the register dimension defined in the Designer whilethe value of the structure item (ProductItem) defines the valuefiltered using this dimension.
In the second line we refer to the manager of the Prices informationregister (InformationRegisters.Prices) and executethe GetLast() method which retrieves the resource values for thelast record in the register corresponding to the transferred date (ActualDate)and the values of the register dimensions (Selection).
The GetLast method retrieves a structure thatcontains the values of the resources. This structure is stored in the ResourceValuesvariable. Actually a register may have multiple resources. Our registercontains only one resource but still a one-item structure will be retrieved.
This is why in the next line we get the required retailprice by simply specifying the name of the resource we want separated by a dot(ResourceValues.Price) and retrieve it when this function isexecuted.
Now this function can be called for at some point in thedocument operation.
Calling the Function upon Product Selection and Filling the Price in the Document
Now our task is as follows. When a ServicesRendered document is edited, wewant the Pricefield to be populated automatically as soon as the user selects a service. In doingso, the service price needs to be based on the date of the created document.
Now locate the ServicesRendered document in the Designer and open the formnamed DocumentForm.
Double-click the ProductListProducts form control or open its properties palette(using Propertiescommand of its context menu). If you now scroll through the end of the list,you will be able to locate the OnChange event that occurs when afield value is changed.
Click the opening button marked with amagnifying glass in the text box.
The system will create a handler procedure template forthis event in the module of our form and will open the Module tab of the form editor.
Populate the module with the following code (listing 9.2).
Listing 9.2. Procedure ProductListProductsOnChange()
// Get current row from the tabular partTabularSectionRow = Items.ProductList.CurrentData;// Set priceTabularSectionRow.Price = CatalogFunctions.RetailPrice(Object.Date, TabularSectionRow.Product);// Recalculate row total DocumentProcessing.CalculateTotal(TabularSectionRow);
Let us review the content of the handler.
You are already familiar with the first line of the handlerafter the procedures ProductListQuantityOnChange and ProductListPriceOnChange.
First of all, we get the current row of the documenttabular section because we will need this row in the future and save it to the TabularSectionRowvariable.
Next we call the earlier created RetailPrice()function from the CatalogFunctionscommon module.
In the first parameter we transfer the document date theprice should be obtained for to the function. The document date is obtainedfrom the default form attribute - Object.Date.
In the second parameter we transfer a link to an item ofthe Productscatalog that is contained in the current row of the document tabular section (TabularSectionRow.Product).
The function retrieves the last value of the price and weassign this value to the Pricefield in the current row of the document tabular section (TabularSectionRow.Price).
Next we call for the CalculateTotalprocedure from the DocumentProcessingcommon module. We created this procedure above in order to recalculate totalsin a document row if price or quantity is modified.
Note that the procedure ProductListProductsOnChange()begins operation in the form module on the front end because it is a handler ofan interactive form event. When a template for this procedure was created, thecompilation directive &AtClient was added automaticallybefore the procedure description.
Next we call for the RetailPrice()function. Since this function cannot be located on the client end, executionwill be transferred to the CatalogFunctions common module that runs on the server. Whenthis function is completed, execution of the program code will continue on theclient.
Why do we use this trick in this situation? Why was itnecessary to transfer code execution to the server?
The thing is that any operations on a database (readingdata, writing) is only possible on the server. In this situation we needed toread the latest data from the information register for some product.
This action is only possible on the server so if you reviewthe description of the GetLast()method of an information register in the Syntax Assistant, you will seethat this method is only available on the server, in the thick client and in anexternal connection.
Thick client and external connection are clientapplications of the previous platform version that exist for compatibility withthe previous applications.
But we develop an absolutely new application that operatesin thin client or web client. So in our situation in order to get some datafrom the database, we need to transfer code execution to the server, obtain therequired data there and return the data to the client. And this is exactly whatwe have done.
In the 1C:Enterprise Mode
Now we will test how our document works.
Launch 1C:Enterprise in the debugging mode and open the Prices informationregister.
For the Philips transistor, we will add a new price for another date(fig. 9.10):
Now open the document Services Rendered No. 1. As you willrecall, we have used this document to "expend" one such transistor.
Leave the document date unchanged and reselect thetransistor in the Productscolumn of the document tabular section. The transistor price applicable as of7/1/2010 will be used automatically. This is the last price value for thedocument date (fig. 9.11).
Fig. 9.11. Filling in Services Rendered Document
Now we will change the document date to 7/13/2010 andreselect the transistor again. A new price value will be applied that is thelast value for this date (fig. 9.12).
Fig. 9.12. Filling in Services Rendered Document
In this manner the document will be populated with theservice price that is valid as of the moment when the document is created.
- What are the uses of the Information Register configuration object?
- What are distinctive features of the Information Register object?
- What are the main differences between an information register and an accumulation register?
- Which fields determine the uniqueness key for an accumulation register?
- What is a periodic information register? What is an independent information register?
- How does one create a periodic information register?
- What is the main register dimension?
- How does one get the resource values for the most recent records in an information register using 1C:Enterprise script?