Stock Adjustment Journal

  • Custom Page
  • Action Page
  • Documents Page
  • Workflow Page
  • Workflow Rules Overview
  • Workflow Rules Details Page
  • View Page
  • View Overview
  • Defining a SapphireOne View Area
  • Using a SapphireOne View Area
  • SapphireOne View Form Events  
  • Converting SapphireOne View Documents  
  • SapphireOne View Database References
  • Project Method References  
  • Field References  
  • Write Page
  • Write Overview
  • Defining a SapphireOne Write Pro Area
  • Storing SapphireOne Write Pro Documents in SapphireOne Object Fields
  • Using a SapphireOne Write Pro Area
  • Printing SapphireOne Write Pro Documents
  • Importing SapphireOne Write Documents    
  • Managing Formulas  
  • Using SapphireOne Write Pro Standard Actions
  • Handling Pictures
  •  Importing and Exporting in .docx Format
  • Exporting to HTML and MIME HTML formats
  • Exporting to SVG Format 
  • SapphireOne Write Pro Language
  • Stock Adjustment Journal Overview

    The SapphireOne Stock Adjustment Journal data entry screen has been designed for the adjustment of stock levels and inventory counts. Inventory counts, as referred to stock-takes in some countries, allows the user to manage your inventory stock levels. While an inventory count is being completed, each item in your warehouse facility is recorded and counted. When the inventory count is submitted, your warehouse inventory levels are recorded and updated.

    Stock-taking or physical verification wall-to-wall or inventory checking is the material verification of the quantities and condition of the inventory items held as inventory within a warehouse or location. This may be done to provide an audit of existing stock. It is also the source of stock discrepancy information.

    Typically, a stock-take may be performed as an intensive end of financial year procedure or alternatively done continuously by means of a rolling stock-take, or sometimes referred to as a cycle count. A cycle count is a periodic inventory auditing process, where you follow a scheduled and repeated sequence of inventory counts on a subset of inventory. Cycle counts contrast with annual stock count of inventory in that a traditional material inventory stops operations at your warehouse or inventory location while all inventory items are counted. Cycle counts are substantially less intrusive and disruptive to daily operations. They execute an ongoing measure of inventory accountability as a procedural verification, and can be curated to focus on inventory of significant financial value, higher movement volume, or that are critical to business processes. Cycle counting is ideally performed in warehouses or locations and is a means of supporting and maintaining an applicable degree of accuracy. Root causes of difficulties can be quickly identified and eradicated in a controlled manner. The effectiveness of the actions can be monitored and reviewed. In contrast, identifying root causes of inventory errors, agreeing on actions to eliminate them to the point of perfecting control processes is virtually impossible with traditional inventory audit approaches. An annual end of financial year inventory stock-take is typically undertaken by the company at the end of the financial year for use in the company’s end of year financial statements being profit and loss, income statement and balance sheet. Including your external auditors is recommended.

    Periodic counting is usually performed on less expensive inventory items. Periodic may refer to daily, weekly, fortnightly, monthly, bi-monthly, quarterly, half-year or annual stock-take.

    A stock-take sale refers to a sale with discounted pricing in a facility, for example a warehouse sale or a warehouse stock clearance to sell off stock from end of life or discontinued inventory lines. This makes the task of stock-taking easier.

    A specific point in time will provide a cut off point that will help determine the stock take level at a particular date and time for your organisation.

    The SapphireOne Stock Adjustment Journal data entry screen has been designed for the adjustment of stock levels and/or actual costs per unit, and allows for control of the stock and automatic entry of the opposing adjustments within the General Ledger.

    The General Ledger account is the Debit or Credit side to be adjusted against the Inventory Asset Account.

    To note before entering a Stock Adjustment Journal Overview:

    • If the Stock Adjustment Journal involves negative stock, there is no cost change.
    • When Stocktake adjustments are done, they must be posted immediately as these entries are based upon a snapshot of the current stock levels at the date and time of entry.
    • The General Ledger Account cannot be the same as the Inventory Asset Account as the Inventory items will be re-valued. Therefore, you will have to create a Stock Variance Account within the Cost of Sales section of your Income Statement.
    • For any Inventory Items with an Inventory Type of “Hire” selected you have to use this Stock Adjustment Journal function to get hire stock into SapphireOne. These items will also not be displayed in any Sales or Purchase lists. (The Hire function is part of the POS drop-down menu.)

    Any data entry field that has a light blue background is a linked data entry field. If you do not know the exact ID to enter, the user may replace some or all of the characters with the “@” or “?” characters. SapphireOne will then display a much shorter list for the user to select the correct ID from. For example,if the user enters “K@” SapphireOne will display all records beginning with K.

    When a data entry field heading is underlined this indicates that once an ID has been entered the user may then click on the underlined heading. SapphireOne will then do a specific query for the ID as entered and display a list with just the single item in it. The user may then view or modify the item as normal.

    Details Area in Stock Adjustment Journal

    How to enter information in the Stock Adjustment Journal Details area:

    1. Notes – Type in any notes.
    2. Document Paperclip – Scan and attach any documents relating to the Stock Adjustment Journal.

    SapphireOne Document Management System (DMS) includes a Paper Clip icon on all data entry and inquiry screens and allows users to attach relevant documents or files to every transaction or record. Additionally, every data entry and inquiry screen within SapphireOne also contains a separate Page specifically for managing documents related to the transaction i.e. version control.

    The red colour of the paper clip indicates that there are currently no documents attached to this transaction. When a document has been attached, the paperclip will turn green and the word Items will be prefixed by the number of documents currently attached to this transaction or record.

    SapphireOne Document Management functionality can store any type of file or document, and an infinite number of documents may be stored for an unlimited amount of time. Examples of types of documents include Adobe Acrobat, Spreadsheet Documents, Word Processor Documents, Photo Files, JPEG, CSV, HEIF, MP4 files.

    Within SapphireOne Master Defaults, there are settings available for the user to restrict the size of each individual document, and also to select where the documents are to be stored – within the data file itself or in a seperate folder. These options may be altered by going to Utilities > Controls > Master Defaults > System Page. Within the Documents area in the right hand corner of SapphireOne Page, there is a provision for the user to set the ‘Document Size Limit’ (the default size is 10Mb). There are also two radio buttons where the user can select ‘Store with Data File’ as part of the data file, and ‘Store as Files’ seperate to the data file.

    To attach a document to a transaction, select either the or Paperclip icon and the following Document List window will be displayed.

    How to Attach Documents Using SapphireOne Paperclip

    Documents can be attached using SapphireOne Drag & Drop functionality. To use this functionality, simply drag a document from the local computer into the Document List screen and it will append automatically. If SapphireOne detects that the document name already exists, a pop-up will be displayed alerting the user. Alternatively, the user can also select the Plus icon to select a document to upload from the local computer.

    Once a document has been attached, the user has the ability to rename any document by right clicking on the file and selecting Rename as seen above. Renaming documents will ensure that document names remain consistent across all records.

    Documents Area within Document Management System (DMS)
    • Open – When the button is selected, SapphireOne will open the currently selected document for viewing.
    • Update – When the button is selected, SapphireOne will display a pop-up which asks the user if they want to Import a New Version of the currently highlighted document. This functionality allows users to update and keep records of different versions of the same document. When the new version has been selected, the user will be asked to enter in a new version number. The new version will now be the document available, and all previous versions will be recorded and available within the History area of Document List screen. The new version of the document will still be linked to any transactions that the old version was.
    • Scan – When the Scan button is selected, SapphireOne will access a local or network scanner, and following the usual prompts allows the user to scan a document directly into the data file and link it to the transaction. The appropriate scanner with software must be installed on the local machine or network.
    • Save – The Save button allows the user to save the currently highlighted document to the disk.
    • Link Documents – The Link Document button allows the user to link the currently highlighted document to another transaction or multiple transactions in the data file. A pop-up will be displayed allowing the user to make their selection. You can learn more about Linked Documents in the Links Area documented below.
    • Link Existing Documents – The Link Existing Documents button allows the user to link an existing document in the data file to this transaction or record. A pop-up will be displayed allowing the user to make their selection from a list of documents. You can learn more about Linked Documents in the Links Area documented below.
    • Delete – The Delete button when selected will delete the currently highlighted document.
    • Plus – When the Plus button is selected SapphireOne will display a search function allowing the user to select a document that is currently on the local computer.

    Details Area within Document Management System (DMS)

    When a document is selected within the Documents area, the Details area will automatically populate to display additional information about the document, including the Title of the document and the Type of file.

    Notes Area within Document Management System (DMS)

    The Notes area is for entering any notes related to the document. The user can select the green clock icon to create a time and date stamp for every note added.

    The Notes area will also keep an automatic user log when any changes are made to the document. For example, if the document is renamed or new links are created. SapphireOne will record the date, time and user that made the modifications.

    Document Details Area within Document Management System (DMS)

    The Document Details area contains additional information relating to the selected document, and will automatically populate when a document is selected from the list. This includes the date and time the document was appended, the document number and the user who added the document.

    History Area within Document Management System (DMS)

    The History area displays a record of the complete version history of the selected document. SapphireOne keeps track of all version changes and will automatically display the documents history within this area.

    The History area will automatically update as new versions of the document are imported when selecting the Update button  . When a new document version is imported, all previous versions of the document will be recorded and available to view within the History area. This enables the user to always view the most recently updated version of the document, however still keep a complete record of the document history.

    The Links area is used to link documents to particular areas or transactions within SapphireOne. The links area can also be used to view all linking information related to the document. For example, if the document was imported using a function with SapphireOne, the links area will have a line containing this linking information.

    To add in additional links to a document, select the document and then select the Link Document icon. The Files pop up window will be displayed. From the File drop down menu, select what you want to link this document to. Then within the Value data entry field, enter in the details (ID). As this data entry field has a blue background, it is user searchable by entering the wildcard ‘?’ or ‘@’ symbols. 

    Updating a Document within Document Management

    The procedure for updating a document is as follows.

    1. When the update button is selected the user will be asked to confirm they would like to import a new version.
    2. Upon confirmation the user will then be asked to choose the updated document to open.
    3. Upon selection a secondary dialogue will prompt the user for the entry of an alphanumeric value for the new version.
    4. Select OK.

    Document Management using SapphireOne Documents Inquiry

    As well as SapphireOne Document Management Paperclip functionality, SapphireOne Documents Inquiry function within SapphireOne Workbook Mode gives users the ability to view a repository of all documents and files stored within the SapphireOne data file. Users have the ability to add New documents, Modify, View or Delete existing documents from within the Documents Inquiry screen.

    Any revisions made to a document within the Documents Inquiry screen will be updated across all areas that the document is linked to across SapphireOne, and similarly any modifications made to documents within the SapphireOne Paperclip Document List window will be reflected within the Documents Inquiry window. For example, if a document is renamed within a transaction Paperclip Document List screen, the document name will also be reflected when viewing the document in the Document Inquiry screen.

    You can learn more about SapphireOne Documents Inquiry functionality within the Documents Inquiry article.

    Document Control within Document Management

    As an example, we have an inventory item with documents attached (installation instructions and a packing checklist amongst others). We add this inventory item to a sales order, manufacture, ship, completely finish the job. One year later we might have a revision of this inventory item along with all the Documents (DMS). Understandably, we don’t want to have to make a whole new inventory item for the revision, just update the DMS that are attached. We update the inventory item with all the new documents, ready for the next sale. When we refer back to the original completed Sales Client Invoice or Job Projects Client Invoice, we will we see the documentation as it was when the Job Project, Sales Client Invoice or Job Projects Client Invoice was completed, or the documents as they are now. In the example above where we have elected to produce an Order Client Invoice (OCI) with the current installation instructions and packing checklist. This will automatically flow into the finished Sales Client Invoice once the OCI has been delivered.

    In the example above we have both the current and historical documents attached. As a SapphireOne user has the ability to edit the list and if they choose not to store the historical document and simply select the Minus button and they can delete the historical document. We also have the ability to modify the existing dociument keeping a log file of each and every time the document has been revised.

    SapphireOne’s implementation of both Dictation (MacOS) and Speech to Text (Windows) is a game changer for data entry. Any data entry field you can type into using a keyboard can use this feature.

    You can also use this functionality on all inquiry screens within SapphireOne. For example, the user is in a Contact within a Client. They may have made a phone call to that particular client using the Softphone technology. Consequently, this will automatically date and time stamp both the contact and the phone number you called.

    As soon as the call is completed, the user has the ability to use Speech to Text (Windows) or Dictation (MacOS). They can dictate into the memo field of the CRM contact, adding as much description as they require.

    Dictation and Speech to Text Procedure

    This functionality applies across every single Data Entry screen. For example, the SapphireOne user is entering a Vendor Invoice (VI). Additionally, you may want to add a memo within the Vendor Invoice (VI). The user can utilise the tool and simply dictate the memo.

    Another example is if the user wants to add additional lines to the General Ledger account, within each General Ledger account. When the user is completing data entry using a General Ledger, there’s always a unique memo field for each GL account line. The user can then utilise this feature to quickly add the information they need to add. Alternatively, you may have an interview with an employee. After the interview process is completed, the user can then make notes about the employee.

    Speech to Text or Dictation is an extremely powerful tool. It is something that we at SapphireOne, as well as our clients, utilise daily. It is a massive timesaver. 

    Information Tab Area in Stock Adjustment Journal

    The Stock Adjustment Journal Information Tab area is used to display extra information about the current entry. You have the ability to view the information here, not alter it.

    Click on the Information Tabs to select the details you would like displayed. The Information Tabs change automatically for the different transactions being viewed. 

    The tabs for this type of transaction include as follows:

    1. Lines – When a transaction line is selected, this tab displays history of the Inventory item. Included in each transaction is the Quantity and Amount, Sequence N°, Date and Type.
      • Create Line – Is for creating a new line and Copy Pricing.
    2. Inventory – When a transaction line is selected, this tab displays inventory details such as ID, Name, Available Stock, Allocated Stock, Stock on Order, Stock on Back Order and Standard Price.
    3. Items – When a transaction line is selected, this tab displays additional inventory details.
    4. Controls – This tab displays information about the transaction such as the date it was created and who created it.
    5. Error Code – Displays any error code such as negative stock, batch error and period error.

    Hiring Inventory Items in Stock Adjustment Journal

    • Any Inventory stock that has its Type set as Hire is treated differently to all other stock.
    • It is not displayed in any Sales or Purchase lists so that the user is unable to directly Purchase Hire items directly into Stock. This also means that accidental Selling or Purchasing of these items is also eliminated.
    • Once the stock has been purchased as a normal Inventory item this Stock Entry function is used to transfer normal stock into the Hire Stock.
    • Before transferring any Inventory items that are to be hired a second Inventory item with a type set as Hire has to be created. That means that for any Inventory item that hiring is planned for will have Two ID’s, One for normal Purchasing and Selling, and another for Hiring.
    • Inventory valuations should also be considered when transferring stock as the new stock that has never been purchased or sold, will have no Last Cost or Price. These will have to be entered manually.

    Tracking Area

    The Stock Adjustment Journal Tracking Details area stores tracking details about the transaction. These details include:

    • Date In – Is the date that this Stock Adjustment Journal has been entered on SapphireOne (usually SapphireOne date).
    • External Reference – External reference number.
    • Ref No – Internal reference number.
    • Period – Period matching the date, set in company controls.

    Transaction Lines Area

    The Stock Adjustment Journal Transaction Lines area contains three data entry lines and a transaction summary area. The three data entry lines consist of:

    1. The 1st line is for the Inventory ID, Inventory Details, GL ID.
    2. The 2nd line has Stocktake quantities, difference, rate, new cost, total and project
    3. The 3rd line has weight area, pallet and 2nd unit details.

    As you enter a transaction, a summary of the transaction appears in a single line in the transaction summary area. You can view or modify a line by selecting it, then proceed to view or modify in the data entry area above.

    How to enter details in the Stock Adjustment Journal Transaction Lines area:

    • Inventory ID – is a linked field and the User can use the Wildcard options to search for the Inventory ID.
    • Stock Quantity – Allows for the changing of the stock quantity.
    • Difference – is the difference between current stock and the stock take. Either positive or Negative –minus.
    • Inventory Details – Once the ID is entered SapphireOne will display the Inventory description or name.
    • Rate – Is the current actual cost per item.
    • New Cost – Field allows for the changing of the current cost per item.
    • Total – This is the total cost for each individual line item including any tax.
    • GL ID – Is a general ledger (GL) ID.
    • Project – Is a linked field and the User can use the Wildcard options to search for the Project ID. SapphireOne will display the Project Name once a valid Project ID has been entered.
    • Weight Area – This field displays the total weight or area x order quantity. The user may enter the total weight required which will automatically update the order quantity.
    • Pallet – Displays the pallet quantity: quantity multiplied by the pallet quantity set in Inventory details.
    • 2nd Unit – Displays total 2nd unit: quantity multiplied by 2nd unit quantity set in Inventory details.

    All of the lines in the Transaction Lines area, are listed here. The list itself, only displays the basic details of each Line. You cannot directly edit from this list.
    To view or modify any line in this Line Listing area, select or highlight a line.
    All of the additional data entry fields will then be displayed for you immediately above the list of lines.
    From there the user is able to view or modify all of the data entry fields for the line as required.

    The easiest way to add a line is with the keyboard shortcut. Hold the  (Command or Control key down and select forward slash (/). SapphireOne will then place the cursor in the Account ID data entry field ready for the entry of a new line. Alternatively, selecting the button will also place the cursor in the Account ID data entry field, ready for the entry of a  new line.
    Lines may also be added to the transaction by clicking on the button or selecting the button to delete the currently highlighted line.

    The Stock Adjustment Journal Transaction Footer is the information bar along the bottom of the screen, and allows the user to easily check critical details of the transaction.

    These details include:

    • Sequence – SapphireOne will generate a unique sequence number for this Stock Adjustment Journal.
    • Tag – The user may mark this transaction using a Tag if required. To add a new Tag category, type the name of new tag into the tag box on the screen and then hit the tab key. Then select ‘Yes’ from the pop-up window to confirm. Alternatively, if you wish to remove a Tag from the list, simply select the drop-down menu and click on the name of the Tag you wish to remove whilst simultaneously holding down the Command (MacOS) or Control (Windows) key. Then select ‘Yes’ from the pop-up window to confirm the deletion from your current list. 
    • Access to More Functions Button Zoom For Current Linked Record-Button
      • Export Lines – Export Lines allows the user to export the lines from any inventory or job project base transactions. This allows the user to export lines, then the client or vendor receives an email with a text file attachment, which they can then import into their SapphireOne ERP.
      • Discount – Allows for the generation of an overall discount on the transaction based on either a fixed dollar value or a percentage.
    • Zoom for Current Linked Record Button Zoom For Current Linked Record-Button – Clicking on the icon once minimises the header for a reduced screen view showing only transaction lines. The icon will then change to maximise, and by clicking on it again it will return the screen to the standard view.

    Note that a tag with the name of HOLD is built into SapphireOne. When it is selected the transaction may not be posted until the tag status of HOLD is removed or altered to something other than HOLD.

    • Many of the Tag Headings are user configurable.
      • The Tag Headings may be re-named by going to:
        Utilities \ Controls \ Master Defaults \ then select the appropriate functions Page
    • Initially all of the tag menus are blank. This means that the user is able to create customised tag drop down menus as required.
      • These drop-down menus are created by entering an item that is not on the list, then (tab away). SapphireOne will ask if you want to add the new tag to the list.
      • To remove a tag, hold the Control or Command key down and then select the tag that you want to remove. You will be asked if you want to remove it from the list.

    SapphireOne checks that each transaction entry is complete and balanced before allowing any saving operation. When the Out of Balance is 0.00 the tick, will activate in the top tool bar indicating to the user that the transaction is ready to be saved. When more than a single transaction is selected, Blue will also be displayed on the main toolbar. See below for additional details.

    You can save your Transaction in one of three methods:

    Select the Tick when it is activated. This will save the current transaction and return the user to the main tool bar or the list.
    When multiple transactions have been selected the user may click on the tick on the tool bar with the results as seen as above.
    Or
    Click on either of the the Arrows. This will tell SapphireOne to save the current transaction and open the next transaction in the list ready for data entry or modification. Also note that for what ever page is open in the transaction SapphireOne will move to the next transaction displaying the exact same page. I.e. Terms page to Terms page. Very handy when checking the same data in multiple items.
    Selecting the Enter Key on the keypad. SapphireOne will then save the current transaction and opens another transaction of the same type ready for data entry. Very handy when entering multiple transactions of the same type. I.e. Client Receipt, Client Receipt.

    Custom Page

    For the existing default names as entered by SapphireOne, the first number indicates the order that it is in the group, and the second number denotes how long the actual data entry field is for the entry of user data. For example, ASAlpha_1_20 denotes that the Data Entry Field is the 1st data entry field in the group, and it will allow up to 20 characters. ASAlpha_8_80 denotes that is is the 8th data entry field in the group with a maxim limit of 80 Characters.

    While this screen shot is from an Asset Inquiry, the procedure for the user to customise this page is exactly the same no matter what function the Custom Page resides in. All of the data entry fields in these Custom Pages may be used in reports in the same manner that other data entry fields are reported on in SapphireOne.

    1. First write down the exact names of the headings that you want to change on the Custom Page. Then go to: Utilities / Controls / Change Names. Please note that you will receive a warning that only one user is to be logged in when this procedure is being executed.
    2. The Change Names function dialog box as seen to the left will be displayed. Next refer to your list of names and scroll down the list until you find them.
    3. One at a time, highlight the name, then enter in your new name in the lower data entry field. After you enter each one you must select the button to write the new name into SapphireOne.

    Action Page

    The Action Page is a separate table that can be added to the major records and transaction tables. This includes actionable items such as Calendar Reminders, Meeting Invites, Alarms, Emails, To-Do Lists, General Notes, Private Notes, Meeting Notes with Date and Time, Start and Finish stamps plus All Day Notifications.

    You can Add or Delete Actions . If you double click on an existing Action it will open, ready to be modified.

    • Diary Area
      • Sequence – SapphireOne will automatically enter in a unique sequence number.
      • Title – Enter in a title for this action.
      • Type – Use the user customisable drop down menu to enter in a type. This will then form a permanent type within the drop-down.
      • Action – Use the user customisable drop down menu to enter in an Action. This will then form a permanent action within the drop-down.
      • User – SapphireOne will enter in the user who is creating this action although, this may be altered if required.
      • Private – If this check box is selected SapphireOne will only allow the User as entered to view or modify this action.
      • Status – The user has three options.
        • Open – Action is open and active.
        • Hold – Action is active but no alarms will be active.
        • Completed – Action is now Inactive and will not be displayed in any list of actions.
      • Tag – A tag may be attached to an action. This will then form a permanent tag within the drop-down. To add a new Tag category, type the name of new tag into the tag box on the screen and then hit the tab key. Then select Yes from the pop-up window to confirm. Alternatively, if you wish to remove a Tag from the list, select the drop-down menu and click on the name of the Tag you wish to remove whilst simultaneously holding down the Command (MacOS) or Control (Windows) key. Then select Yes from the pop-up window to confirm the deletion from your current list. 
      • Link – When created from within a transaction or a record, a link to the transaction or record is automatically created by SapphireOne. When created from the Options Menu, Palette or Workbook, the user will have to select from the drop down menu if the action is to be linked to an item or function. There are 12 items on this list from Clients to Manager.
    • Check List area – A user created check list for creating actions. A check box is provided so that a user can selected them off as they progress.
    • Dates and Times Area:
      • Start/Finish – You can set an action to have a Start and a Finish time, or select the check box for an all Day option.
      • Completed – Once an action has a completed date entered it will no longer be active and displayed in any lists of actions.
    • Alarm Area – An alarm can be set to email someone at a certain date and time, or send your user a reminder and/or email if the email has been entered.
    • Recurring Area – If necessary the alarm may be set to at set periods established by the Type drop down menu. The recurring period may also be set by date if required.
    • Notes Area – You can select the Green clock icon to add Time and Date stamps to your notes. You can also highlight the text in the Notes area and right mouse click to customise the Font, Style, Colour and Background Colour to your preference.
    • Invite Attendees Area – You can invite multiple attendees to your event and keep track of if they have accepted or rejected your invite. These attendees can be notified by email if the email has been entered.

    Documents Page

    The Documents Page is used to store and record documents and information relating to data entry, transactions and master tables.

    Documents Area

    Any type of document can be attached to the Documents area. Examples of types of documents include Adobe Acrobat, Spreadsheet Documents, Word Processor Documents, Photo Files, JPEG, CSV, HEIF, MP4 files and more.

    Documents can be attached using Drag & Drop functionality. To use this functionality, simply drag a document or file from the local computer into the Document List screen and it will append automatically.

    Please note that when creating a new record in SapphireOne, you are unable to attach a document until the record has an entered ID.

    There are eight buttons and icons on the Document List screen. These are as follows:

    • When the button is selected SapphireOne will open the currently highlighted document for viewing. (The appropriate software must be installed on the local computer or device).
    • When the button is selected SapphireOne displays a popup which asks the user if they want to Import a New Version of the currently highlighted document. (The new version will still be linked to any transactions as was the old version).
    • When the Scan button is selected SapphireOne will access a scanner, and following the usual prompts allows the user to Scan a Document Directly into the data file and link it to this transaction. (The appropriate scanner with software must be installed on the local computer, device or network).
    • The Save button allows the user to save the currently highlighted document.
    • The Link Document button allows the user to link the currently highlighted document to other transaction or transactions in the data file. A popup will be displayed allowing the user to make their selection.
    • The Link Existing document button allows the user to link an existing document in the data file to this transaction or record. A popup will be displayed allowing the user to make their selection from a list of documents.
    • The Delete button when selected will delete the currently highlighted transaction or record.
    • When the Add button is selected SapphireOne will display a search function allowing the user to select a document that is currently on the local computer or device.

    Details Area

    The Title and Type of the document are displayed in the Details Area.

    Last Modified Area

    The documents area keeps a record of the Time and Date of when the document was last modified in addition to who initially added it.

    Workflow Page

    Workflow Rules Overview

    A Workflow Rule must be established before entering any transactions. The rule is written into the transaction itself upon entry and will remain even if the workflow rule applying to the transaction is deleted. If a workflow rule is altered and there are existing transactions that require the new workflow rule to be applied to them, they will have to be deleted and re-entered under the new Workflow rule.

    The Workflow Rules functionality enables the setting of workflow rules that will require the approval of a user, group of users, a level of users or the creator. SapphireOne has the ability to create workflow rules on any data entry type of transaction within SapphireOne. The data entry can then have any or multiples of the combination of the 12 workflow rules applied to it. For example, these include New Transactions, Modify Transaction, Deleted Transactions, Transaction Above a Particular Dollar ($) Value, Transaction Sales Under Average Cost, Transaction for Client Over Credit Limit, Transaction for Client on Credit Stop, Transaction Sales with Negative Stock, Leave Request, Tracking Notes, Bank Details and Sales under floor price.

    Each workflow rule can have a unique Title and Tag established by the user. Once the transaction type, as well as the rule trigger, has been established, the user has the ability to add unique notes to each workflow rule. The SapphireOne user then proceeds to the flow, which contains stages where the they have the ability to create unlimited stages. The workflow rule can have one stage or multiple stages, often they tend to be sequential. The user can set the amount of stages they require and within each stage they have the ability to set the number of people required to Approve or Notify a workflow rule before authorisation is granted.

    As an example, if you set five stages it will not progress to stage two until stage one has been approved. Within Stage 1 you may have 5 users authorised to approve Stage 1 but it will require a minimum of 3 out of the 5 users to Approve or Notify stage one before it can advance to Stage 2. This is referred to as levels within the stage. You may assign a group of people to a level and assigning a Type can be done either by User, Level or Creator. For each Type, the user also has three checkboxes which are Authorisation Required, Hierarchical Authorisation and Email notification.

    Another example, if you’ve established a workflow rule around Leave Requests, Stage One may be an employee entering a Leave Request. Stage One simply moves straight to Stage Two because that’s been established. Stage Two may then be that the manager is notified. Stage Three may then include the HR department approving the leave and Stage Four may be to the original creator i.e. the employee has an email notification that their leave has been approved or not approved.

    Initially these new transactions will have an error of WF for Workflow and cannot be printed, converted, emailed or posted until they are approved or authorised by the user or a group of users, level and/or creator. If they are rejected, the transactions will then remain in the list with a stratus of error indicating the continuing WF error.  They may then be left as they are and since they will remain un-posted or deleted as required. 

    For each rule with a Workflow entry there must be a user or group of users setup with a restriction where they will create all or some transactions with an error code of WF.

    There must also be a user or group of users set up to approve the transactions. The switch is the selection made from thetwo2 checkboxes, Authorisation Required or Hierarchical Authorisation.

    Workflow Rules Details Page

    Entering a New Workflow Rule

    The Change button seen in the screenshot below is directly linked to the Organisation Chart function on the Controls drop-down menu. The Organisation Chart function is simply a means to place a number of users in a hierarchical group. It is documented in a separate article on Organisation Chart.

    Details Area

    The available options are as follows.

    • Sequence – SapphireOne will enter a sequentially generated number and it may not be altered.
    • Title – Enter in a Name or Title for this workflow entry.
    • Tag – Enter in a Tag if required. Remember that this list of tags may be setup by the user as required.
    • Company – SaphireOne should enter the company but if it does not, enter the company.
    • Department – Enter a department if required. 
    • Transaction – Select from the from the extensive list of transactions when the blue arrow is selected. For every type of transaction the user may then setup individual rules as required.
    • Rules Trigger – Then select from the Rules Trigger list box, a rule that is to be applied. Once the selected rule is broken the workflow function will become active and activate the Workflow function.
      • Transactions – The first three rules will raise a WF error. If the user tries to Create a New Transaction, or Modify or delete a transaction.
      • Above $ – This option will raise a WF error when any transaction is over a specified dollar amount.
      • Average Cost – Any transactions under average cost will raise a WF error.
      • Credit Limit and Stop – These two options will raise a WF error when the conditions are met.
      • Negative stock – Any transaction that will take inventory into a negative stock level will also raise the WF error if this option is selected.
      • Leave Request –  If any user makes a leave request a WF will be displayed enabling the HR officer to be alerted.
      • Tracking Notes – This will generate a WF. This is used to to alert the user responsible for managing tracking notes.
      • Bank Details – This linked to SapphireOne’s G/L accounts that are bank accounts.
      • Floor Price – When this option is selected A WF error will be sent to the selected user allowing them to approve or disapprove the sale.
    • Stages – Next set the number of hierarchical stages that must be navigated before the WF error is removed. Each stage will occupy a column in each row in the flow list towards. If required up to 6 stages or levels of authorisation is provided for, although 6 levels would be challenging to manage. To simplify it, the entry of the number 3 here will setup up three columns in the flow area below with default headings and that is all.
    • Single Stage – If only a single level of approval is required leave the Stage set at 1 for a single level of approval. The flow area below will display just the single item across the entire row as seen to the right.
    • Multiple Stages – If more stages or levels are required enter in a number from 2 to 6. The additional stages will be added as additional columns in the flow area as seen to the right.
    • Notes – Any notes for this workflow rule may be entered here.

    Now that we have created a rule for a transaction we now have to select to how it is to be applied. We now enter into the Flow area the Users or the Level of users that the rule is to be applied to.

    Flow Area

    • New Button – To enter in a new event the following procedure must be followed.
      • Column or Stage Selection – The user must first select select the column and then select the button in the top right-hand corner of the Flow area. SapphireOne will place the word User in the column that was selected.
      • Multiple Stages – Repeat the procedures above for each column or stage in the work flow function. From now on once one of the stages in the line has been selected, it will alter to the orange colour as seen below.
    • Stage Selection – The user must now select each stage in sequence and for every stage set up the following details.
      • Stage – SapphireOne will add a suffix of the stage number to the name Stage. The user may then enter in a column heading name for the stage if required.
      • Type – The user has 2 choices here, Approve or Notify. If approve is selected the user will have to proceed through the approval process before the Work Flow error will be removed for them. If notify is selected the user will only have to open the transaction for viewing.
      • Number – The number entered here indicates the number of users that have to approve this transaction before the WF error is removed from the transaction. Zero means none and 5 means five. Be careful here as the default is usually not wanted so a number will have to be manually entered.

    Party Group

    For each stage this area sets up the users and what tasks they are to perform for this Work Flow function.

    • Type – This will determine how the workflow rule will be applied.
      • User – When this option is selected a data entry field will be displayed allowing the user to enter in a selected users ID linking the rule to a single selected user. Once a user ID has been selected SapphireOne will display the selected users ID.
      • Level – When this option is selected the Change button will be displayed. When it is selected SapphireOne will display the organisational chart allowing the user to select an organisational level for this rule to be applied to. Once a level has been selected SapphireOne will display the name of the level selected.
      • Creator –  When this option is selected, SapphireOne will allow the creator of the transaction to process the transaction.
    • Authorisation Required checkbox – This checkbox is crucial in relation to the Workflow Rules function. When selected, SapphireOne will enforce the WF error for the selection made in the Link radio buttons. If it is not selected SapphireOne will allow the user to create and save transactions as listed without a WF error as normal. However they will also receive the active message pop up dialog when there are transactions within SapphireOne created by other users that meet the criteria as set up in the Workflow rule.
      • Selected – Restricted saving of the selected transactions with WF error.
      • De-Selected – All transactions saved normally and permission to approve selected transactions.
    • Hierarchical Authorisation Checkbox – If this checkbox is selected, SapphireOne will allow anyone above the level that has been entered for the stage to authorise the transaction. 
    • Notes – Finally enter any notes for this workflow entry. 

    SapphireOne’s implementation of both Dictation (MacOS) and Speech to Text (Windows) is a game changer for data entry. Any data entry field you can type into using a keyboard can use this feature.

    You can also use this functionality on all inquiry screens within SapphireOne. For example, the user is in a Contact within a Client. They may have made a phone call to that particular client using the Softphone technology. Consequently, this will automatically date and time stamp both the contact and the phone number you called.

    As soon as the call is completed, the user has the ability to use Speech to Text (Windows) or Dictation (MacOS). They can dictate into the memo field of the CRM contact, adding as much description as they require.

    Dictation and Speech to Text Procedure

    This functionality applies across every single Data Entry screen. For example, the SapphireOne user is entering a Vendor Invoice (VI). Additionally, you may want to add a memo within the Vendor Invoice (VI). The user can utilise the tool and simply dictate the memo.

    Another example is if the user wants to add additional lines to the General Ledger account, within each General Ledger account. When the user is completing data entry using a General Ledger, there’s always a unique memo field for each GL account line. The user can then utilise this feature to quickly add the information they need to add. Alternatively, you may have an interview with an employee. After the interview process is completed, the user can then make notes about the employee.

    Speech to Text or Dictation is an extremely powerful tool. It is something that we at SapphireOne, as well as our clients, utilise daily. It is a massive timesaver. 

    Checking for WF Transactions

    User Work Flow Alert – For any user that is required to approve any work flow transactions there will be an additional button displayed at the right-hand end of the tool bar as seen here .

    When the user selects this button SapphireOne, will display an alert dialog indicating how many work flow transactions that require their attention for processing. 

    Organisation Levels and Mixed Permissions

    Note that the Organisation Levels referred to here are from the Organisation Chart function on the controls drop-down menu. 

    When Organisational Levels are used when setting permissions for Workflow Rules, the Levels are not hierarchical in the level above a user will not have automatic authorisation permissions granted. If this was allowed everyone above the working level would be viewing authorisation alerts including the General Manager or CFO. 

    Authorisation may only be assigned at a particular level by selecting the Authorisation Required checkbox for any user or groups of users in SapphireOne. 

    If authorisation permission is to be set at the User Level the users should not have the Rules Level set in their user file on the first page of a user Inquiry the Details Page. Care will also have to be exercised when Organisation levels are used with users at a user by user basis. 

    Probably be the most common error when setting up this function is the setting up of a conflict. For example, authorisation has been granted for Sales Managers and Authorisation Required for the user SapphireOne Sydney who is also in the Sales Managers group. That is a direct conflict must be avoided at all costs as the user has been included as part of the Sales managers level. 

    Do not mix permissions. Make certain that a specific user who may not authorise transactions does not also form part of any organisational level that may authorise transactions. 

    Workflow In Operation (Restrictions)

    A user creates a transaction and saves it. SapphireOne determines that a workflow rule is to be enforced as it has determined that for the type of transaction there is a rule that is broken and the check box has been selected. SapphireOne will then proceed to save the transaction with a status of err for error. The error code will be WF for Workflow and this means that a user with the appropriate authorisation rule in place has to approve it which will remove the error code enabling further processing of the transaction as documented on the previous page. 

    From SapphireOne setup we have two types of users who will require authorisation or be able to authorise transactions. 

    1. User who starts or creates the Transaction. The users ID will be recorded by SapphireOne and they will be the only user to receive the Active Message pop up for the transactions that they actually create. Until a user actually creates a transaction they will not receive any Active Message authorisation pop ups. OR Specific Users for example, SONE0 SapphireOne Syd. I.e. a new staff member and the management wants to check certain transactions before they are processed. Again, they will be the only users to receive the Active Message pop up only for the transactions that they actually create. 
    2. User Level. This is different as this will be a group of users who have the same Rules Level set in the first page of their User Access Inquiry. Once a transaction has been created by a single member of the Rules Level Group all of the users in the same group would receive the Active message pop up. For example, if there is more than one user with a Level of Sale Manager set in their user file they would all be presented with the Active message pop up. 

    Workflow In operation (Approvals)

    The rules for approvals is the same as for restrictions above only in reverse. For example, some planning will be required for the rules. If the organisational chart levels are used throughout and you have 100 sales staff and 1 sales manager set to authorise transactions the Active Message pop up above will be displayed to 101 users and this may not be what is wanted. 

    Setting up Rules

    The Authorisation Required check box must only be selected for any user who is permitted to authorise transactions. 

    There are three options when selecting a user or users when setting rules for authorisation and these are detailed below. 

    1. On a user by user basis so that the actual user ID will have to be entered and this could be used in two ways. For a specific user who is to authorise transactions, or to a single user that management has selected to check on all transactions created by that user before they are processed further. (New Staff).
    2. On an Organisational Level basis. This could be used when a group of users is to be selected from the organisational chart. For example, Sales Staff could be set up so that all transactions that they create would require authorisation. It should be noted that a problem could arise in that this would mean that not only will all Sales Staff not be permitted to authorise transactions, that they would then all be presented with the Active Message on the previous page for each and every transaction created by each and every user in the Sales Staff grouping and this could become annoying. 
    3. Probably the best option for setting Authorisation Rules is to use the User who start transaction option. While this could be set either way by the selection of the Authorise Required checkbox the normal procedure would be to not select the Authorise Required checkbox. SapphireOne would then require that all transactions created in SapphireOne be authorised, but the only users being presented with the Active Message pop up would be the user who created the transaction and any user that has the Authorisation Required check box selected. 

    Two events per Rule

    As seen below for each and every rule set up there must be at least two events setup. One that requires authorisation and one that does not require authorisation as seen below. It is all very well to have a WF error on a transaction, but there must be at least one staff member who can approve any WF transactions that are created. 

    Examples

    From the Organisation Chart referred to above we will discuss three scenarios. 

    1. Sales Staff – Setup users performing sales or purchases in the AccPayableStaff level.
      • The Authorisation Required checkbox is selected.
    2. Sales Managers- Set up one or more users as Sales Managers in the AccPayableMan level.
      • The Authorisation Required checkbox would not be selected.
    3.  End result – All Sales staff will create transactions with an WF error requiring the Sales Manager to approve them all. The Active Message alert will be displayed to all 100 staff members plus the Sales Manager.
    1. User Who creates the Transaction- For the user who creates the transaction.
      • The Authorisation Required checkbox is selected.
    2. Sales Managers- As above set up one or more users as Sales Managers in the AccPayableMan level.
      • The Authorisation Required checkbox would not be selected.
    3. End Result – All Sales staff will create transactions with an WF error requiring the Sales Manager to approve them all. The Active Message alert will be displayed to the user who created the transaction and the Sales Manager. Even if another user modifies the transaction the only user who receives notification messages will be the user who created the transaction and the Sales manager.
    1. User – If necessary for any transaction created, a specifically selected user may be set up to receive notifications regarding all transactions with workflow errors. This Sales Staff user must not have a Level of Sales Staff set in their user file or else a conflict will arise.
      • Select User from the Change button options.
      • The Authorisation Required checkbox is selected.
    2. Sales Managers- Set up one or more users as Sales Managers in the AccPayableMan level.
      • The Authorisation Required checkbox would not be selected.
    3. End Result – Only the Accounts manager and the entered user would receive any alerts for Workflow.

    Try and make certain that only 1 user has authorisation privileges granted and does not belong to any other group or organisational level.  If 2 specific users or levels have authorisation privileges All of them will have to authorise transactions before the WF error code is released unless they are part of an organisational level. 

    View Page

    View Overview

    The Sapphire View tool enables the user to embed advanced spreadsheet features in their forms. A spreadsheet is an accounting tool or application that allows for the storage, organisation and analysis of data and displays it in a table format. A spreadsheet is comprised of a number of cells in which information or numerical data can be entered into, calculations executed or display pictures.

    The Sapphire View tool gives the SapphireOne user the ability to insert and display a spreadsheet area in your SapphireOne forms. Once you use SapphireOne View areas in your forms, you can import and export spreadsheets documents using the SapphireOne View commands. When executed in forms, SapphireOne View areas provide basic spreadsheet features including cell editing and formula entry. More advanced features are available through the SapphireOne View language.

    Sapphire Web Pack View is a functionality and a SapphireOne form area that enables developers to embed advanced spreadsheet features in their forms. 

    View Installation and Activation  

    Unlike with the legacy SapphireOne View product, SapphireOne View features are directly included in SapphireOne itself, making it easier to deploy and manage. No additional installation is required.

    However, SapphireOne View requires the same license as SapphireOne View. You need to have this license installed in your application in order to use these features. When the SapphireOne View license is not installed, the contents of an object that requires a SapphireOne View feature are not displayed at runtime and an error message is displayed instead.

    In this example, a SapphireOne View license is missing while displaying a SapphireOne View spreadsheet area:

    Defining a SapphireOne View Area

    View Overview  

    SapphireOne View allows you to insert and display a spreadsheet area in your SapphireOne forms. A spreadsheet is an application containing a grid of cells into which you can enter information, execute calculations, or display pictures.

    Once you use SapphireOne View areas in your forms, you can import and export spreadsheets documents using the SapphireOne View commands.

    Creating the Area  

    SapphireOne View documents are displayed and edited manually in a SapphireOne form object named SapphireOne View. This object is available as part of the last tool (Plug-in Area, Web Area, etc.) found in the object bar:

    A SapphireOne View form area is configured by means of standard properties found in the Property List, such as Object Name and Variable or ExpressionCoordinatesDisplayAction, and Events

    • Object Name: name of the SapphireOne form area that contains and displays the SapphireOne View document.
    • Variable or Expression: name of the SapphireOne View form area variable.

    When the form is executed, the SapphireOne View area displays a spreadsheet by default:

    Using a SapphireOne View Area

    View Overview  

    When executed in forms, SapphireOne View areas provide basic spreadsheet features including cell editing and formula entry. More advanced features are available through the SapphireOne View language.

    Selection, Input and Navigation Basics  

    Spreadsheets are composed of rows and columns. A number is associated with each row. A letter (or group of letters once the number of columns surpasses the number of letters in the alphabet) is associated with each column. The intersection of a row and a column makes a cell. Cells can be selected and their contents edited.

    Selection  

    • To select a cell, simply click on it or use the direction arrows on the keyboard. Its content (or formula) is displayed within the cell. 
    • To select several continuous cells, drag the mouse from one end of the selection to the other. You can also click on the two ends of the selection while holding down the Shift key.
    • To select all cells in the spreadsheet, click on the  cell at the top left of the area. 
    • To select a column, click on the corresponding letter (or set of letters).
    • To select a row, click on the corresponding number.
    • To select a group of cells that are not continuous, hold down the Ctrl key (Windows) or Command key (Mac) and click on each cell to be selected. 
    • To deselect cells, simply click anywhere within the spreadsheet.

    Input and Navigation  

    Double-clicking on a cell allows passing into input mode in the relevant cell. If the cell is not empty, the insertion cursor is placed after the content of the cell. 

    Data can be entered directly once a cell is already selected, even if the insertion cursor is not visible. The input then 
    replaces the content of the cell.

    The Tab key validates the cell input and selects the cell to its right. Combining the Shift + Tab keys validates the cell input and selects the cell to its left. 

    The Carriage return key validates the cell input and selects the cell below it. Combining the Shift + Carriage return keys validates the cell input and selects the cell above it. 

    The direction keys (arrows) allow you to move a cell in the direction indicated by the arrow.

    View User Interfaces  

    You can add an interface to SapphireOne View areas to allow end users to perform basic modifications and data manipulations. SapphireOne offers two optional interfaces to choose from, Ribbon and Toolbar. These interfaces can be enabled or disabled from either the Property List or dynamically with code:

    • Property List: In the Appearance section. 
    • Dynamically: Via a JSON file (see Dynamic Forms)
      • “userInterface”: Default value is “none”. To enable a toolbar, it can be set to “ribbon” or “toolbar”.
      • “withFormulaBar”: Default value is “false”. To enable the formular bar, it can be set to “true” . Note: Available only for the “toolbar” interface. 

    Both the Ribbon and the Toolbar interfaces group related actions into the following tabs: 

    Tab  Actions Ribbon Interface Toolbar Interface
    File File manipulation  X  
    Home Text appearance  X  X
    Insert Add items  X  X
    Formulas Formula calculation and library  X  X
    Data Data manipulation  X  X
    View Visual presentation  X  X
    Settings Sheet presentation reference  X  

    User-defined modifications are saved in the SapphireOne View object when the user saves the document.

    View Ribbon  

    The Ribbon interface allows end users to perform comprehensive modifications and data manipulations

    View Toolbar  

    The Toolbar interface allows end users to perform basic modifications and data manipulations. 

    Enabling the Toolbar interface displays the Show Formula Bar option. When selected, the formula bar is visible below the Toolbar interface. If not selected, the formula bar is hidden.

    With visible formula bar:

    Entering a Formula, a Function or a Reference  

    To enter a formula or a function in a SapphireOne View area:

    1. Select the cell into which you will enter the formula or function.
    2. Enter = (the equal sign).
    3. Enter the formula.
      OR
      Click on a cell to enter its reference in the formula.

      OR
      Type the first letter of the function to enter. A pop-up menu listing the availables functions and references appears, allowing you to select the desired elements:

    Context Menu  

    SapphireOne View areas benefit from an automatic context menu that provides users with standard editing features such as copy and paste, but also with basic spreadsheet features:

    Note: The Copy/Cut and Paste features of the context menu only work within the spreadsheet area, they do not have access to SapphireOne pasteboard. System shortcuts such as Ctrl+c/Ctrl+v works however and can be used to exchange data between the area and other applications.

    This menu proposes additional features depending on the clicked area:

    • click on a column or row header: InsertDeleteHide, or Unhide the contents
    • click on a cell or a cell range:
      • Filter: allows hiding row through filters (see Filtering rows in the SpreadJS documentation).
      • Sort: sorts the column contents.
      • Insert Comment: allows user to enter a comment for an area. When a comment has been entered for an area, the top left cell of the area displays a small red triangle:

    SapphireOne View Form Events  

    Overview  

    The following form events are available in the Property List for SapphireOne View areas:

    Some of the events are standard form events (available to all active objects) and some are specific SapphireOne View form events. The specific SapphireOne View form events provide additional information in the object returned by the FORM Event command when they are generated for SapphireOne View areas. The following table shows which events are standard and which are specific SapphireOne View form events:

    Standard SapphireOne events (see Form event code) Specific SapphireOne View events
    On Load   On VP Ready
    On Getting Focus  On Clicked
    On Losing Focus   On Double Clicked
    On Unload   On Header Click
      On After Edit
      On Selection Change
      On Column Resize
      On Row Resize
      On VP Range Changed

    On VP Ready  

    Any SapphireOne View area initialization code, for loading or reading values from or in the area, must be located in the On VP Ready form event of the area. This form event is triggered once the area loading is complete. Testing this event makes you sure that the code will be executed in a valid context. An error is returned if a SapphireOne View command is called before the On VP Ready form event is generated.

    Note: SapphireOne View areas are loaded asynchronously in SapphireOne forms. It means that the standard On load form event cannot be used for SapphireOne View initialization code, since it could be executed before the loading of the area is complete. On VP Ready is always generated after On load.

    On Clicked  

    Clicking anywhere on a SapphireOne View document generates the On Clicked event. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Clicked
    description text “On Clicked”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range

    Example: If(FORM Event.code=On Clicked)
        VP SET CELL STYLE(FORM Event.range;New object("backColor";"green"))
     End if

    On Double Clicked  

    When a user double clicks anywhere on a SapphireOne View document, the On Double Clicked event is generated. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Double Clicked
    description text “On Double Clicked”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range

    Example: If(FORM Event.code=On Double Clicked)
        $value:=VP Get value(FORM Event.range)
     End if

    On Header Click  

    A user clicking on a column or row header in a SapphireOne View document generates the On Header Click event. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Header Click
    description text “On Header Click”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range
    sheetArea longint The sheet location where the event took place: 0: The crossing area between column number/letter headers (top left of the sheet)1: The column headers (area indicating the column numbers/letters)2: The row headers (area indicating the row numbers)

    Example: If(FORM Event.code=On Header Click)
        Case of
           :(FORM Event.sheetArea=1)
              $values:=VP Get values(FORM Event.range)
           :(FORM Event.sheetArea=2)
              VP SET CELL STYLE(FORM Event.range;New object("backColor";"gray"))
           :(FORM Event.sheetArea=0)
              VP SET CELL STYLE(FORM Event.range;New object("borderBottom";New object("color";"#800080";"style";vk line style thick)))
        End case
     End if

    On After Edit  

    Following any user modification in a SapphireOne View document, the On After Edit event is generated. The object returned by the FORM Eventcommand contains:

    Property Type Description
    code longint On After Edit
    description text “On After Edit”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    action text “editChange”, “valueChanged”, “DragDropBlock”, “DragFillBlock”, “formulaChanged”, “clipboardPasted”

    Note: See also the On VP Range Changed event.

    Depending on the action property value, the object will contain additional properties.

    action = editChange  

    Editing text generates the following additional properties:

    Property Type Description
    range object Cell range
    editingText variant The value from the current editor

    action = valueChanged  

    Changing value(s) generates the following additional properties: 

    Property Type Description
    range object Cell range
    oldValue variant Value of cell before change
    newValue variant Value of cell after change

    action = DragDropBlock  

    Dragging and dropping actions generate the inclusion of the following additional properties:

    Property Type Description
    fromRange object Range of source cell range (being dragged)
    toRange object Range of the destination cell range (drop location)
    copy boolean Specifies if the source range is copied or not
    insert boolean Specifies if the source range is inserted or not

    action = DragFillBlock  

    Dragging content to fill adjacent cells generates the following additional View:

    Property Type Description
    fillRange object Range used for fill 
    autoFillType longint Value used for the fill. 0: Cells are filled with all data (values, formatting, and formulas)1: Cells are filled with automatically sequential data2: Cells are filled with formatting only3: Cells are filled with values but not formatting4: Values are removed from the cells5: Cells are filled automatically 
    fillDirection longint Direction of the fill. 0: The cells to the left are filled1: The cells to the right are filled2: The cells above are filled3: The cells below are filled

    action = formulaChanged  

    Entering formula(s) generates the following additional properties:

    Property Type Description
    range object Cell range
    formula text The formula entered 

    action = clipboardPasted  

    Pasting content from the clipboard generates the following additional properties:

    Property Type Description
    range object Cell range receiving the contents
    pasteOption longint Specifies what is pasted from the clipboard: 0: Everything is pasted (values, formatting, and formulas)1: Only values are pasted2: Only the formatting is pasted3: Only formulas are pasted4: Values and formatting are pasted (not formulas)5: Formulas and formatting are pasted (not values)
    pasteData object The data from the clipboard to be pasted
       Property Type Descriptiontext textThe text from the clipboardhtml textThe HTML from the clipboard

    View Example  

    Here is an example handling an On After Edit event: If(FORM Event.code=On After Edit)
        If(FORM Event.action="valueChanged")
           ALERT("WARNING: You are currently changing the value from "+String(FORM Event.oldValue)+" to "+String(FORM Event.newValue)+"!")
        End if
     End if

    The above example could generate an event object (see FORM Event) like this:
    {
    "code":45;
    "description":"On After Edit";
    "objectName":"ViewProArea"
    "sheetname":"Sheet1";
    "action":"valueChanged";
    "range": {area:ViewProArea,ranges:[{column:1,row:2,sheet:1}]};
    "oldValue":"The quick brown fox";
    "newValue":"jumped over the lazy dog";
    }

    On Selection Change  

    Modification of the current selection of rows or columns in a SapphireOne View document generates the On Selection Change event. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Selection Change
    description text “On Selection Change”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    oldSelections object Cell range before change. 
    newSelections object Cell range after change. 

    Example: If(FORM Event.code=On Selection Change)
        VP SET CELL STYLE(FORM Event.oldSelections;New object("backColor";Null))
        VP SET CELL STYLE(FORM Event.newSelections;New object("backColor";"red"))
     End if

    On Column Resize  

    When a user modifies the width of a column in a SapphireOne View document, the On Column Resize event is generated. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Column Resize
    description text “On Column Resize”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range of the columns whose widths have changed
    header boolean True if the row header column (first column) is resized, else false

    Example: If(FORM Event.code=On Column Resize)
        VP SET CELL STYLE(FORM Event.range;New object("hAlign";vk horizontal align right))
     End if

    On Row Resize  

    A user modifying the height of a row in a SapphireOne View document generates the On Row Resize event. The object returned by the FORM Eventcommand contains:

    Property Type Description
    code longint On Row Resize
    description text “On Row Resize”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range of the rows whose heights have changed
    header boolean True if the column header row (first row) is resized, else false

    Example: If(FORM Event.code=On Row Resize)
        VP SET CELL STYLE(FORM Event.range;New object("vAlign";vk vertical align top))
     End if

    On VP Range Changed  

    When a change occurs within a cell range in the SapphireOne View document, the On VP Range Changed event is generated. The object returned by the FORM Event command contains:

    Property Type Description
    objectName text SapphireOne View area name
    code longint On VP Range Changed
    description text “On VP Range Changed”
    sheetName text Name of the sheet of the event
    range object Cell range of the change
    changedCells object Range containing only the changed View. It can be a combined range. 
    action text The type of operation generating the event:”clear” – A clear range value operation”dragDrop” – A drag and drop operation”dragFill” – A drag fill operation”evaluateFormula” – Setting a formula in a specified cell range”paste” – A paste operation”setArrayFormula” – Setting a formula in a specified cell range”sort” – Sorting a range of cells

    Converting SapphireOne View Documents  

    You can convert your SapphireOne View documents to SapphireOne View areas using the VP Convert from SapphireOne View command. Most properties and information stored in SapphireOne View documents are automatically converted, including formats, styles, borders, values, formulas, selections, zoom, etc. In general, converted SapphireOne View documents will be rendered in SapphireOne View areas exactly as they were rendered in SapphireOne View areas, like the following:

    Original SapphireOne View document:

    Document converted in SapphireOne View area

    We are doing our best to ensure that converted documents remain as true as possible to the original, but some features may not be fully rendered. These are described in the paragraph below.

    View Conversion Process  

    Note: The SapphireOne View document conversion feature is being continuously improved, based on customer feedback. It is highly recommended to always keep a copy of your original SapphireOne View BLOBs or documents, even after a successful conversion. 

    With regards to the current state of your SapphireOne View plug-in document, the conversion process requires the following steps.

    1. Load your SapphireOne View document (.4pv) into a BLOB:
      Note: If your SapphireOne View document is already stored in a BLOB field, go to step 2.
       C_BLOB($pvblob)
       DOCUMENT TO BLOB("document.4PV";$pvblob)
    2. Call the VP Convert from SapphireOne View with the BLOB containing the SapphireOne View document:
       C_OBJECT($vpObj)
       $vpObj:=VP Convert from SapphireOne View($pvblob)
    3. Assign the resulting object to a SapphireOne View area form object or a document to see the results. 
       VP IMPORT FROM OBJECT("SapphireOneViewProArea";$vpObj)

    Conversion Details  

    The following table provides the current status for the primary conversion areas. Note that this list will be updated regularly, as the conversion process is continuously improved. 

    Feature Conversion status Comments
    Document attributes Document display attributes are converted: selected cells, zoom, grid display.
    Document information is converted: version, title, subject author, company, note, creation and modification date.
    Columns and rows All defined columns and rows are converted with their original size.
    Column and row headers are converted without any restrictions.
    Borders Borders are converted with their thickness and color. Grid display settings are converted. Only one single bar border and one double-bar border models are available in SapphireOne View. Single bar borders are converted the same as the original, any double-bar borders are converted to the SapphireOne View double-bar model.
    Splitters Currently not converted
    Styles & fonts Styles and style sheets are converted. Conditional styles are not supported. Deprecated text styles (i.e. Shadow, Condensed, etc.) and QuickDraw fonts are not converted. 
    Rotation styles (oriented text) are currently not converted
    Formats & cell names Cell formats are converted to available formats with similar rendering. All data type formats are supported: text, number, date and time, boolean, picture. Cell names are converted. COMPATIBILITY NOTE: As of SapphireOne v17 R5, SapphireOne View default formats rely on the same regional settings as the SapphireOne host database. 
    User defined SapphireOne formats (starting with “|”) are currently not converted
    Controls created with PV SET CELL CONTROL (button / radio button / check box / drop down / combo box) are currently not supported
    Invisible cells are not supported (not available in SapphireOne View) Only columns, rows, or sheets can be set invisible. An alternate solution is to use VP ADD FORMULA NAME to define non-displayed values or formulas.
    Pictures Pictures are supported and converted with some limitations SapphireOne View picture format included multiple codecs and is deprecated. Converted pictures keep only the most appropriate codec for html rendering (svg, png, jpeg, gif) and are saved in base64. 
    Pictures with truncated centered / replicated format are currently not converted Background pictures are not replicated on each page (this concept does not exist in SapphireOne View).
    Printing Currently not supported Printing options and print settings defined in the SapphireOne View document are converted. 
    Dynamic links Cells or columns linked to fields or variables are currently not supported
    Formulas Formulas are converted but for security reasons, references to SapphireOne project methods, commands, variables, or fields need specific processing (see below) See Converting SapphireOne View plug-in formulas.
    Project methods – supported Project methods must comply with SapphireOne View requirements (see Project method references). A non compliant method name is converted to UNSUPPORTED_SapphireOneMETHOD_NAME(“<method name>”,param1,…paramN).
    Commands – supported Converted to existing SapphireOne View functions (see Functions and SapphireOne commands). SapphireOne commands that are not part of the authorized list are converted to: UNSUPPORTED_SapphireOneCOMMAND(<command name>,param1,…,paramN). 
    Variables – not supported You must use SapphireOne project methods to access variable values (see Project method references). Variables in formulas are converted to UNSUPPORTED_VARIABLE(“<variable name>”).
    Fields – supported Converted to “TABLETITLE_FIELDTITLE()” if available in the database during conversion. If a field or table name is not ECMA compliant, converted to UNSUPPORTED_TABLE_FIELD_TITLE(“virtual structure name”). Only fields belonging to the “virtual structure” of the database can be called in SapphireOne View formulas. See Field references.

    SapphireOne View Database References

    Project method references  

    Field references  

    Project Method References  

    Overview  

    SapphireOne View allows you to call SapphireOne project methods from within your formulas. Using SapphireOne project methods extends the possibilities of your SapphireOne View documents. SapphireOne methods can receive parameters from the SapphireOne View area, and return values. For security reasons, only methods that have been explicitly allowed can be called by the user. 

    Requirements  

    To be called in a SapphireOne View formula, a project method must be:

    • Referenced: it was explicitly declared using the VP SET CUSTOM FUNCTIONS command (recommended) or the VP SET ALLOWED METHODS command.
    • Runnable: it belongs to the host database or a loaded component with the “Shared by components and host database” option enabled (see Sharing of project methods).
    • Not in conflict with an existing SapphireOne View function: if you call a project method with the same name as a SapphireOne View built-in function, the function is called.

    Note: If neither the VP SET CUSTOM FUNCTIONS nor the VP SET ALLOWED METHODS command has been executed during the session, SapphireOne View custom functions rely on allowed methods defined by SapphireOne’s generic SET ALLOWED METHODS command. In this case, the project method names must comply with JavaScript Identifier Grammar (see ECMA Script standard). The global filtering option in the Settings dialog box (see Data Access) is ignored in all cases.

    Hello World example  

    We want to print “Hello World” in a SapphireOne View area cell using a SapphireOne project method:

    1. Create a “myMethod” project method with the following code:
       #DECLARE->$hw Text
       $hw:="Hello World"
    2. In the form method of the form that contains the SapphireOne View area, you can write:
       Case of
          :(Form event code=On Load)
             var $o : Object
             $o:=New object
        // Define "vpHello" function from the "myMethod" method
             $o.vpHello:=New object
             $o.vpHello.formula:=Formula(myMethod)
      ("ViewProArea";$o)
       End case
    3. Edit the content of a cell in a SapphireOne View area and type:

      “myMethod” is then called by SapphireOne and the cell displays:

    Parameters  

    Parameters can be passed to SapphireOne project methods using the following syntax:=METHODNAME(param1,param2,...,paramN)

    These parameters are received in methodName in $1, $2…$N.

    Note that the ( ) are mandatory, even if no parameters are passed:=METHODWITHOUTNAME()

    You can declare the name, type, and number of parameters through the parameters collection of the function you declared using VP SET CUSTOM FUNCTIONS command. Optionally, you can control the number of parameters passed by the user through minParams and maxParams properties.

    If you do not declare parameters, values can be sequentially passed to methods (they will be received in $1, $2…) and their type will be automatically converted. Dates in jstype will be passed as C_OBJECT in SapphireOne methods with two properties:

    Property Type Description
    value Date Date value
    time Real Time in seconds

    SapphireOne project methods can also return values in the SapphireOne View cell formula via $0. The following data types are supported for returned parameters:

    • C_TEXT (converted to string in SapphireOne View)
    • C_REAL/C_LONGINT (converted to number in SapphireOne View)
    • C_DATE (converted to JS Date type in SapphireOne View – hour, minute, sec = 0)
    • C_TIME (converted to JS Date type in SapphireOne View – date in base date, i.e. 12/30/1899)
    • C_BOOLEAN (converted to bool in SapphireOne View)
    • C_PICTURE (jpg,png,gif,bmp,svg other types converted into png) creates a URI (data:image/png;base64,xxxx) and then used as the background in SapphireOne View in the cell where the formula is executed
    • C_OBJECT with the following two properties (allowing passing a date and time):
      PropertyTypeDescriptionvalueDateDate valuetimeRealTime in seconds

    If the SapphireOne method returns nothing, an empty string is automatically returned.

    An error is returned in the SapphireOne View cell if:

    • the SapphireOne method returns another type other than those listed above,
    • an error occurred during SapphireOne method execution (when user click on “abort” button).

    Field References  

    Overview  

    SapphireOne View allows you to use references to SapphireOne database fields in your formulas. When displaying a SapphireOne View area, a field reference is replaced by the field value in the current record. The value is extracted when the form is opened, but if it changes you can just call VP RECOMPUTE FORMULAS so that the SapphireOne View area uses the new value.

    Requirements  

    To be called in a SapphireOne View formula, a SapphireOne field must comply to the following requirements:

    • the field was declared as a formula using the VP SET CUSTOM FUNCTIONS command (see example).
    • the field type must be supported by SapphireOne View (see below).

    An error is returned in the SapphireOne View cell if the formula calls a field which is not compliant.

    Note: For security when the VP SET CUSTOM FUNCTIONS is not used (not recommended), only the fields belonging to the virtual structure of the database, i.e. declared through the SET TABLE TITLES and/or SET FIELD TITLES commands with the * parameter, can be called. In this case, table and field names must be ECMA compliant (see ECMA Script standard). 

    Supported Field Types  

    SapphireOne View supports references to fields of the following types:

    Type Value type in SapphireOne View
    Alpha, Text string
    Integer, Long integer, Integer 64-bit, Real, Float number
    Date JavaScript Date type (hour, minute, sec = 0)
    Time JavaScript Date type (date in base date, i.e. 12/31/1899)
    Boolean bool
    Picture supported picture types: jpg, png, gif, bmp, svg; other types converted into png. Creates an uri (data:image/png;base64,xxxx) set as background for the SapphireOne View cell where the formula is executed

    Example  

    We want to print the name of a person in a SapphireOne View area cell using a SapphireOne field:

    1. Create an “Employee” table with a “L_Name” field:
    2. In the form method of the form that contains the SapphireOne View area, you can write:
       Case of
          :(Form event code=On Load)
             var $o : Object
             $o:=New object
             $o.EMP_NAME:=New object //declare the function
             $o.EMP_NAME.formula:=Formula([Employee]L_Name)
             VP SET CUSTOM FUNCTIONS("ViewProArea";$o)
       End case
    3. Edit the content of a cell in the SapphireOne View area and enter “=e”:
    4. Select EMP_NAME (use the Tab key) and enter the closing ). 
    5. Validate the field to display the name of the current employee:

      Note: The [Employee] table must have a current record.

    Note: When the VP SET CUSTOM FUNCTIONS command is not used (not recommended), fields declared in the virtual structure are entered with a syntax such as TABLENAME_FIELDNAME()


    You can review our Blog and YouTube channel for additional information and resources on SapphireOne ERP, CRM and Business Accounting software.

    Write Page

    Write Overview

    The Sapphire Write tool is additioanlly found on all tools menus in SapphireOne.

    SapphireOne Write Pro offers SapphireOne users an advanced word-processing tool, fully integrated with your SapphireOne database. Using SapphireOne Write Pro, you can write pre-formatted emails and/or letters containing images, a scanned signature, formatted text and placeholders for dynamic variables. You can also create invoices or reports dynamically, including formatted text and images.

    The key features of Write are:

    • SapphireOne Write compatibility: a SapphireOne Write Pro object can open and convert legacy SapphireOne Write documents while supporting most of their specific properties.
    • Word processing: a SapphireOne Write Pro object embedded in a form provides standard word-processing features, including text and style manipulation, image insertion, import and export, and much more.
    • Database integration:
      • A SapphireOne Write Pro object can display variable parts which will be filled with data from the database, or data computed by SapphireOne.
      • SapphireOne Write Pro documents can be stored within database fields or on disk.

    Installation and Activation  

    SapphireOne Write Pro is no longer a plug-in but is fully integrated into SapphireOne itself, making it easier to deploy and manage. No additional installation is required; you can add SapphireOne Write Pro areas to your forms and handle SapphireOne Write Pro variables directly in your SapphireOne applications.

    However, note that SapphireOne Write Pro uses the same license as SapphireOne Write. You need to have this license installed in your application in order to enable the feature. 

    Requirements: On Windows, SapphireOne Write Pro features rely on Direct2D. With Windows 7 or Windows Server 2008 machines, make sure the Platform Update for Windows has been installed so that the required Direct2D version is available.

    About Write Pro 

    Note that SapphireOne Write Pro objects can be handled using specific commands (see “SapphireOne/4D Write Pro Language” theme) as well as commands from other SapphireOne themes (“Objects (Forms)” and “Styled Text” themes).

    Defining a SapphireOne Write Pro Area

    Creating the Write Area  

    SapphireOne Write Pro documents are displayed and edited manually in a SapphireOne form object: SapphireOne Write Pro. This object is available as part of the last tool (Plug-in Area, Web Area, etc.) found in the object bar:
     
     
     

    A SapphireOne Write Pro form area is configured by means of standard properties found in the Property List, such as Object Name and Variable NameCoordinatesEntryDisplayAppearance, and/or Events.
     

     

    The Variable Name property can be used in the language as a reference to the SapphireOne Write Pro area. Note that the variable must be of the Object type (for more information, refer to the C_OBJECT command). 

    “Entry” properties manage basic features for text entry:

    • Enterable: enables you to lock/unlock the area in order to allow or prevent editing
       
    • Auto Spellcheck: available for SapphireOne Write Pro areas
       
    • Context Menu: allows you to enable/disable the context menu in Application mode (see the Using a SapphireOne Write Pro area section) 
       
    • Selection always visible: handles text selection as in standard text areas. 

    Using the SapphireOne Write Pro Widget of the Object library  

    You can create a preconfigured SapphireOne Write Pro area using the SapphireOne Write Pro object found in the Object library (“Entry areas” theme):
     

     

    This area comes with a control panel for managing all the attributes of the area (font, color, style, etc.):

    For more information, refer to the SapphireOne Write Pro area section.

    Configuring Drag and Drop 

    To configure the drag and drop features for your SapphireOne Write Pro areas, you need to select the appropriate options in the “Action” theme of the Property List:
     

    SapphireOne Write Pro areas support two drag and drop modes:

    • Custom mode: only “Draggable” and “Droppable” options checked. In this mode, you can select text and start to move it. The object method is then called with the On Begin Drag Over event, and you can define the drop action using custom code. 
       
    • Automatic mode: “Draggable”, “Droppable”, “Automatic Drag” and “Automatic Drop” options checked. In this mode, you can automatically move or copy the selected text by pressing the Alt/Option key. The On Begin Drag Over event is not triggered.

    Note: Selecting only “Automatic Drag” and “Automatic Drop” options will have no effect in the SapphireOne Write Pro area.  

    Configuring Write View Properties  

    Document view properties are directly available in the Property List for SapphireOne Write Pro areas. They allow you to define how a SapphireOne Write Pro document will be displayed by default in the SapphireOne Write Pro area. These properties let you customize, for example, whether SapphireOne Write Pro documents are displayed as they would be printed, or as they would be rendered in a browser. You can set different views of the same SapphireOne Write Pro document in the same form.

    Note: View settings can be managed dynamically using the WP SET VIEW PROPERTIES and WP Get view properties commands. 

    Document view settings are handled through specific items in the Appearance theme of the Property List for SapphireOne Write Pro form objects:
     

    • Resolution: Sets the screen resolution for the SapphireOne Write Pro area contents. By default, it is set to 72 dpi (macOS), which is the standard resolution for SapphireOne forms on all platforms. Setting this property to Automatic means that document rendering will differ between macOS and Windows platforms. Setting a specific dpi value will make the document rendering the same on both macOS and Windows platforms.
    • Zoom: Sets the zoom percentage for displaying SapphireOne Write Pro area contents.
    • View mode: Sets the mode for displaying the SapphireOne Write Pro document in the form area. Three values are available:
      • Page: the most complete view mode, which includes page outlines, orientation, margins, page breaks, headers and footers, etc. For more information, please refer to the Page view features paragraph.
      • Draft: draft mode with basic document properties
      • Embedded: view mode suitable for embedded areas; it does not display margins, footers, headers, page frames, etc. 
        This mode can also be used to produce a web-like view output (if you also select the 96 dpi resolution and the Show HTML WYSIWYG option).

        Note: The View mode property is only used for onscreen rendering. Regarding printing settings, specific rendering rules are automatically used (see Printing SapphireOne Write Pro documents).

    • Show page frame: Displays/hides the page frame when Page view mode is set to “Page”.
    • Show references: Displays all SapphireOne expressions inserted in the document as references. When this option is unchecked, SapphireOne expressions are displayed as values. When you insert a SapphireOne field or expression, SapphireOne Write Pro computes and displays its current value. If you wish to know which field or expression is displayed, check this option. The field or expression references then appear in your document, with a gray background.

      For example, you have inserted the current date along with a format, the date is displayed:
       

       
      If you check the Show references option, the reference is displayed:
       

       
      Note: SapphireOne expressions can be inserted using the ST INSERT EXPRESSION command.

    • Show headers/footers: Displays/hides the headers and footers when Page view mode is set to “Page”. For more information on headers and footers, please refer to the Using a SapphireOne Write Pro area section. 
    • Show background: Displays/hides both background images and background color.
    • Show hidden characters: Displays/hides invisible characters
    • Show HTML WYSIWYG: Enables/disables the HTML WYSIWYG view, in which any SapphireOne Write Pro advanced attributes which are not compliant with all browsers are removed.
    • Show horizontal ruler: Displays/hides the horizontal ruler. For more information on rulers in SapphireOne Write Pro areas, see the Handling rulerssection.
    • Show vertical ruler: Displays/hides the vertical ruler when the document is in Page mode. For more information on rulers in SapphireOne Write Pro areas, see the Handling rulers section.

    Compatibility notes:

    • SapphireOne Write Pro documents created with versions up to SapphireOne v15 R5 are displayed using the default values for these properties, with the exception of the Resolution property, which is set to Automatic in this case.
    • Horizontal rulers are available by default in databases created starting with SapphireOne v16 R2; for databases converted from previous versions, this setting is not checked by default.

    Storing SapphireOne Write Pro Documents in SapphireOne Object Fields

    You can store your SapphireOne Write Pro documents automatically in the SapphireOne data file. If you created a SapphireOne Write Pro area on a form and created an Object field to store the area’s contents, any text entered in the area is saved automatically with each record when the record is validated. You can then use the QUERY BY ATTRIBUTE command in order to select records based on the value of their internal attributes. You can also add and query your own attributes with SapphireOne Write Pro areas.  

    This section describes the following features:

    • Binding a SapphireOne Object field to a SapphireOne Write Pro area in a form
    • Setting, getting, and querying custom attributes of stored SapphireOne Write Pro documents using the OB SETOB Get standard object commands, and QUERY BY ATTRIBUTE

    Assigning a SapphireOne Object Field to a SapphireOne Write Pro Area  

    To bind a SapphireOne Write Pro area with a SapphireOne Object field, you just need to reference the field in the Variable Name property of the area. 

    Creating the Object Field in the Structure  

    In your database structure, any SapphireOne Object field can be used to store SapphireOne Write Pro documents. As with any Object field, you just have to define its standard properties, according to your needs:

    • the field name,
    • its attributes, such as “Expose with SapphireOne Mobile Service,” as well as its index, 
    • its storage option (for more on this, see External data storage).

    Assigning the Object Field to the SapphireOne Write Pro Area  

    Once you have defined an Object field to store your SapphireOne Write Pro document, you just need to reference it in the form containing the area. You can use any table or a project form. 
    In the Form editor, enter the field name using the standard “[Table]Field” notation in the Variable Name area of the Property list for the SapphireOne Write Pro area:

    Your SapphireOne Write Pro area is then associated with the field, ensuring that its contents will be saved automatically with each record. Note that if you do not use the SapphireOne automatic action buttons, you will have to save the area manually using SapphireOne commands. 

    Using Write Custom Attributes  

    When SapphireOne Write Pro areas are stored in Object fields, you can save and read any custom attributes with the SapphireOne Write Pro document, such as, for example, the writer’s name, the document category, or any additional information you may find useful. You can then query your custom attributes to select records matching the criteria.

    Custom attributes will be exported with the WP EXPORT DOCUMENT or WP EXPORT VARIABLE commands. They will be exported as well when converting a SapphireOne Write Pro Object field to JSON using the JSON Stringify command (along with the SapphireOne Write Pro main document attributes).

    To set or get custom attributes, you just need to use object notation or the OB Get and OB SET commands.

    For example, in the form method, you can write: If(Form event code=On Validate)
        [MyDocuments]MySapphireOneWP["myatt_Last edition by"]:=Current user
        [MyDocuments]MySapphireOneWP.myatt_Category:="Memo"
        [MyDocuments]MySapphireOneWP:=[MyDocuments]MySapphireOneWP //to record the edit
     End if

    or: If(Form event code=On Validate)
        OB SET([MyDocuments]MySapphireOneWP;"myatt_Last edition by";Current user)
        OB SET([MyDocuments]MySapphireOneWP;"myatt_Category";"Memo")
     End if

    You can also read custom attributes of the documents: vAttrib:=[MyDocuments]MySapphireOneWP.myatt_Category

    or: vAttrib:=OB Get([MyDocuments]MySapphireOneWP;"myatt_Category")

    If you have saved custom SapphireOne Write Pro attributes in your data file, you can query these attributes to create a selection of records containing the appropriate attribute value. In the following example, you query the table containing the Object field to select records: QUERY BY ATTRIBUTE([MyDocuments];[MyDocuments]MySapphireOneWP;"myatt_Category";=;"Memo")
      //selects all records in MyDocuments whose "myatt_Category" custom attribute has the value "Memo"
      //in the MySapphireOneWP Object field (bound to a SapphireOne Write Pro area)

    Note about custom attribute names: Since custom attributes share the same naming space as SapphireOne Write Pro internal attributes, we strongly recommend that you use prefixes when defining your own attribute names in order to avoid any conflicts between internal and custom attributes. Non-prefixed names are reserved for SapphireOne Write Pro internal attributes. You can use any custom prefix (for instance, we used “myatt_” as a prefix in the above example).

    Note: Starting with SapphireOne v15 R4, SapphireOne Write Pro internal attributes can also be accessed through programming using the standard QUERY BY ATTRIBUTEOB Get and OB SETcommands, but also using WP SET ATTRIBUTESWP GET ATTRIBUTES and WP RESET ATTRIBUTES. For more information, please refer to the SapphireOne Write Pro Attributes section.

    Using a SapphireOne Write Pro Area

    Managing documents in SapphireOne Write Pro areas  

    In SapphireOne applications, SapphireOne Write Pro documents are created, imported, and exported by means of specific commands found in the SapphireOne Write Protheme (WP EXPORT DOCUMENTWP EXPORT VARIABLEWP Import documentWP New).

    You can also associate a SapphireOne Write Pro area with an Object field in a database form. This way, each SapphireOne Write Pro document is automatically saved with the record and stored in the database’s data (see Storing SapphireOne Write Pro documents in SapphireOne Object fields). 

    .4wp Document Format  

    You can save and re-open SapphireOne Write Pro documents to and from disk without any loss using the native .4wp format. 

    The .4wp format consists of a zip folder whose name is the document title and whose contents are HTML text and images:

    • HTML text combines regular HTML with SapphireOne expressions (which are not computed) as well as SapphireOne-specific tags,
       
    • images are stored in a folder with the same name as the document title, next to the HTML file.

    Since .4wp documents are based on HTML, they can be imported or opened in any external application supporting HTML. 

    Note: The SapphireOne Write Pro internal document format is a proprietary HTML extension, compatible with HTML5/XHTML5, but which supports its own subset of HTML/CSS attributes and tags. As a result, only HTML documents exported by SapphireOne Write Pro can be opened by SapphireOne Write Pro without any risk of data loss. Importing HTML documents that were created externally could produce errors.

    Write User Interface  

    If the Context menu property is checked for a SapphireOne Write Pro area (see Defining a SapphireOne Write Pro area), a comprehensive context menu is available to users in the Application mode:
     

     

    This menu offers access to all the SapphireOne Write Pro user features.  

    Selecting the Write View Mode  

    SapphireOne Write Pro documents can be displayed in one of three page view modes:

    • Draft: draft mode with basic properties
       
    • Page (default): “print view” mode 
       
    • Embedded: view mode suitable for embedded areas; it does not display margins, footers, headers, columns, page frames, etc. This mode can also be used to produce a Web-like view output (if you also select the 96 dpi resolution and the HTML WYSIWYG option).

    The page view mode can be configured by means of the area pop-up menu:
     

     

    Note: The page view mode is not stored with the document. 

    For areas embedded in SapphireOne forms, the view mode can also be set by default using the Property List. In this case, the view mode is stored as a property of the SapphireOne Write Pro form object (for more information, please refer to the Configuring View properties paragraph). 

    Write Page View Features  

    When the document is in Page view mode, the following document properties are displayed for the user:

    • Page outlines to represent printing limits
       
    • Page width and Page height (default: 21×29.7 cm)
       
    • Page orientation (default: Portrait)
       
    • Page margin (default: 2.5 cm)

    In addition, specific paragraph properties are available in the Paragraph… submenu:
     

     

    • Widow and orphan control: When this option is checked for a paragraph, SapphireOne Write Pro does not allow widows (last line of a paragraph isolated at the top of a page) or orphans (first line of a paragraph isolated at the bottom of a page) in the document. In the first case, the previous line of the paragraph is added to the top of the page so that two lines are displayed there. In the second case, the single first line is moved onto the next page.
       
    • Avoid page break inside: When this option is checked for a paragraph, SapphireOne Write Pro prevents this paragraph from being broken into parts on two or more pages. 
       

    You can also use additional page-related commands such as Insert page/column/section break, Document…/Page size or Document…/Page orientation

    Note: When a document is in Embedded or Draft view mode, page properties can be set, even if their effect is not visible. In Draft view mode, the following paragraph property effects are visible:

    • Page height limitation (lines drawn)
    • Columns 
    • Avoid page break inside property
    • Widow and orphan control.

    Background  

    The background of SapphireOne Write Pro documents and document elements (tables, paragraphs, sections, headers/footers, etc.) can be set with the following effects:

    • colors
    • borders
    • images
    • origin, horizontal and vertical positioning
    • painting area
    • repeat

    These attributes can be defined programmatically for either individual elements on a page and/or entire document backgrounds with the WP SET ATTRIBUTES command or by Using SapphireOne Write Pro standard actions. To see the full list of available background attributes and where they can be applied, see the SapphireOne Write Pro Attributes article.   

    Users can modify background attributes via the contextual menu as shown below:

    Handling Headers, Footers, and Sections in Write Pro

    SapphireOne Write Pro documents support headers and footers. These headers and footers are related to sections.

    A section is a part of a document which is defined by a page range and can have its own paging and common attributes. A document can contain any number of sections (from just one, up to the total number of pages). Each page can only belong to one section, except pages with continuous section breaks (see below). 

    You can define a set of headers and footers for each section.

    Defining a Section  

    A section is a subset of continuous pages in a SapphireOne Write Pro document. A document can contain one or more sections. A section can contain any number of pages, from a single page to the total number of pages in the document. A section page can contain a single column or up to 20 column(s). 

    By default, a document contains a single section, named Section 1. The SapphireOne Write Pro contextual menu displays this section number wherever you click in the document:
     

     

    You create a new section by adding a section break in the text flow:
     

     

    When a section break has been added, the contextual menu displays an incremented number for each section. You can, however, rename any section:
     

     

    The name you entered is then used as the section name everywhere in the document:
     
     
     

    Note that if you have defined a different first page or different left/right pages for a section, the page type is also displayed in the menu (see below).

    Inserting a Continuous Section Break  

    A continuous section break creates a new section on the same page. This allows you to create pages with sections that have different numbers of columns (see Creating a page with multiple-column and single column sections).

    Sections created with continuous section breaks are counted in the document (they have section numbers), but unlike sections created with regular section breaks, their headers, footers, anchored images, etc. are only taken into account when a physical page break has occurred.

    Note: If you change the page orientation for the new section after you insert a continuous section break, it turns into a regular section break.

    Section Attributes  

    Sections inherit attributes from the document. However, common document attributes, including headers and footers, can be modified separately for each section. The contextual pop-up menu displays the properties and attributes available at the section level:
     

     

    • Page orientation: allows you to set a specific page orientation (Portrait or Landscape) per section.
       
    • Different first page: allows you to set different attributes for the first page of the section; this feature can be used to create flyleaves, for example. When this attribute is checked, the first page of the section is handled as a subsection itself and can have its own attributes. 
       

       
    • Different left and right pages: allows you to set different attributes for left and right pages of the section. When this attribute is checked, left and right pages of the section are handled as subsections and can have their own attributes.
       

       
    • Columns commands: allow to define the number and properties of columns for the section. These options are detailed below. 
    • Header and Footer commands: these options allow you to define separate headers and footers. These options are detailed below. 
    • Margins / Paddings / Borders / Background: these attributes can be defined separately for each section. For more information on these attributes, please refer the SapphireOne Write Pro Attributesarticle. 

    Inserting Headers and Footers in Write

    Each section can have specific header and footer. Headers and footers are displayed only when the document page view mode is Page

    Within a section, you can define up to three different headers and footers, depending on the enabled options:

    • first page,
    • left page(s),
    • right page(s).

    To create a header or a footer: 

    1. Make sure the document is in Page view mode. 
    2. Double-click in the header or footer area of the desired section and page to switch to editing mode.
      • The header area is at the top of the page:
      • The footer area is at the bottom of the page:

    You can then enter any static contents, which will be repeated automatically on each page of the section (except for the first page, if enabled).

    You can insert dynamic contents such as the page number or the page count using the ST INSERT EXPRESSION command (for more information, please refer to the Inserting document and page expressions paragraph). 

    Note: You can also handle footers and headers by programming using specific commands such as WP Get header and WP Get footer.

    Once a header or a footer has been defined for a section, you can configure its common attributes using the contextual menu:

    For more information on MarginsPaddingsBorders, and Background attributes, please refer the SapphireOne Write Pro Attributessection. 

    You can remove the entire definition of a header or a footer (contents and attributes) by selecting the Remove header or Remove footercommand in the contextual menu. 

    Compatibility  

    SapphireOne Write Pro handles headers and footers of documents converted from the SapphireOne Write plug-in with a fixed height.

    The following expressions and properties are also supported and converted from the SapphireOne Write plug-in headers and footers:

    • page number and page count variables
       
    • distinct first page
       
    • distinct left/right pages

    Handling Rulers  

    Horizontal rulers are available in every viewing mode of SapphireOne Write Pro and have the following characteristics:

    • Graduations in cm, mm, inches or pt according to current layout unit defined in the SapphireOne Write Pro document. You can change measurement units using the context menu or by modifying the wk layout unit attribute.
       
    • First line indent symbol
       
    • Left paragraph margin symbol
       
    • Right paragraph margin symbol
       
    • Tabs displayed along lower edge of ruler
       
    • Visible color contrast representing left and right page margins

    Vertical rulers are available in Page mode only and have the following characteristics:

    • Graduations in cm, mm, inches or pt according to current layout unit defined in the SapphireOne Write Pro document. You can change measurement units using the context menu or by modifying the wk layout unit attribute.
       
    • Visible color contrast representing top and bottom page margins

    You can change the display status of the rulers via standard actions (see Using SapphireOne Write Pro standard actions) or by checking or unchecking the Show horizontal ruler or Show vertical ruler item in the context menu of the SapphireOne Write Pro area:
     

     

    Note: A specific SapphireOne Write Pro area property allows defining the default display for the rulers (see Configuring View properties section).

    Adjusting Text Margins and Indents  

    Horizontal Ruler  

    You can modify the left and right margins, indents and tab positions by clicking and dragging the corresponding symbols on the horizontal ruler:
     

     

    When you hover the mouse over one of these symbols, the cursor changes to indicate that it can be moved, and a vertical guide line appears while you drag it:
     

     

    When multiple paragraphs are selected, dragging margin or indent symbols applies these margins or indents to all selected paragraphs. Holding down the Shift key while dragging these symbols maintains existing intervals between indents or margins in the selected paragraphs. 

    Vertical Ruler  

    You can modify the top and bottom margins with the vertical ruler. When you hover the mouse over the margin limit, the cursor changes to indicate that it can be moved, and a horizontal guide line appears while you drag it:
     
     
     

    This action can be used to modify the spacing between the top and bottom of the page and the body and the header and footer of a document.  

    Managing Tabs  

    You can use the horizontal ruler’s context menu to create, modify or delete tabs:
     

     

    To create a tab, just right-click directly on the horizontal ruler and choose its type from the context menu; a single left click automatically creates a default left tab. You can also right-click on existing tabs to modify their type using the context menu.

    Remove tab is only available when you right-click directly on an existing tab; you can also remove tabs by dragging them outside the horizontal ruler area.

    Notes: 

    • Tabs can also be defined programmatically with the WP SET ATTRIBUTESWP GET ATTRIBUTES, and WP RESET ATTRIBUTES commands with the wk tab default and wk tabsselectors.
    • For decimal tabs, SapphireOne Write Pro considers the first dot or comma character from the right as the decimal separator; this default setting can be modified with the wk tab decimal separatorselector. 

    Define leading characters  

    The characters preceeding tabs (leading characters) can be defined by selecting from five predefined characters or by designating a specific character to use. The predefined characters are:

    • None (no characters are displayed – default)
    • ….      (dots)
    • —      (dashes)
    • __     (underscores)
    • ***     (asterisks)

    Leading characters always appear before the tab and follows the text direction (left to right or right to left). They can be defined programmatically with the WP SET ATTRIBUTESWP GET ATTRIBUTES, and WP RESET ATTRIBUTES commands using wk leading with the wk tab default or wk tabs selectors, or via the horizontal ruler’s contextual menu (as shown below).

    When Other… is selected, a dialog is displayed where a custom leading character can be defined.

    Multi-Column Rulers  

    When two or more columns are defined for the document or the section, the horizontal ruler displays a specific area for each column:

    Note: Multi-column feature is not available in Embedded view mode. 

    On After Edit Event  

    An On After Edit form event is triggered for a SapphireOne Write Pro area form object whenever any of the tab or margin controls are moved, added or deleted, whether by dragging them or using the context menu.

    Handling Columns  

    SapphireOne Write Pro allows you to manage columns in your documents. Columns are chained from the left-most column to the right-most column. In other words, when entering text, the text flow will start filling the left column and continue with the column directly to the right until it reaches the end of the page. Once the end of the page is reached, the text flow cycles through the next page. In order to be able to balance the page settings, SapphireOne Write Pro allows you to insert column breaks.

    Columns can be defined at the document level (they are displayed in the whole document) and/or at the section level (each section can have its own column configuration). 

    Note: Columns are supported in Page view mode and Draft view mode only (they are not displayed in Embedded view mode), and they are exported to .docx using WP EXPORT DOCUMENT but not to HTML and MIME HTML formats (wk web page complete format).

    Columns can be set using:

    You can set or get the following properties and actions for columns:

    Property Description Documentattributes Standard actions
    Number of columns You can define up to 20 columns for the document/section wk column count columnCount
    Column spacing Space between columns in pts, inches, or cm. Note that all columns will have the same size. Each column width is automatically calculated by SapphireOne Write Pro according to the number of columns, the page width, and the spacing wk column spacing columnSpacing
    Column width (read-only attribute) Current width for each column, i.e. computed width wk column width
    Column rule style, color, and width You can add a vertical separator (a decorative line) between columns. These options let you design the separator style, color and width. To remove the vertical separator, select None as a style. wk column rule style, wk column rule color, wk column rule width columnRuleStylecolumnRuleColorcolumnRuleWidth
    Insert break Insert a column break wk column break, see also WP INSERT BREAK insertColumnBreak
    Columns menu Create a Columns sub-menu columns

    Creating a Page with Multiple-Column and Single Column Sections  

    Inserting a continuous section break in your document allows you to have multiple-column sections and single column sections on the same page. 

    For example:

    You can insert a continuous section break and change the number of columns to two for the first section:

    Handling Tables  

    SapphireOne Write Pro documents can contain tables. SapphireOne Write Pro tables are created and defined by programming, but their contents can be modified and handled by the user. Various SapphireOne Write Pro table attributes are editable, including row height, alignment, margins, text style, color, or borders.  

    Creating a Table  

    SapphireOne Write Pro tables are created by calling the WP Insert tablecommand. You can then add rows by using the WP Table append rowcommand.

    Note: A user can create a table by copying and pasting a range of cells: 

    Editing Tables  

    Cell contents can be added by programming using the WP Table append row command.

    Once a table is created, cell contents can also be edited at runtime by users. They can click into cells and select, edit, copy/paste, or delete text or pictures just like in regular paragraphs. They can navigate through cells using the Tab key (Shift+Tab to navigate in opposite direction). 

    Using the Carriage return key within a cell creates a new paragraph in the cell. 

    Note that cell width is fixed: when a user enters text or pastes a picture, the height of the row is automatically extended if necessary and text automatically wraps: 

    Users can also select columns, rows, or cells and apply available attributes regarding text style, colors, alignment, etc. using the built-in pop up menu or any customized interface. SapphireOne Write Pro provides several commands to select any parts of a table:

    (*) Columns do not have equivalent in html. In SapphireOne Write Pro, a column range is actually a range of cells, which means that columns have the same priority as cells.

    Once you have selected a range, you can apply any appropriate attribute using the WP SET ATTRIBUTES command. Within cells, attributes are applied to paragraphs, characters, or pictures, depending on their contents. For example, you can set the height, font size, border, padding, etc. of tables or table cells (for more information, please refer to the SapphireOne Write Pro Attributes section). 

    When different attributes are applied to concurrent elements of a table, a priority order is applied for the rendering:

    1. Table is rendered first
    2. Rows are rendered (overriding table attributes)
    3. Cells/Columns are rendered (overriding row attributes). 

    Resizing Columns  

    The width of table columns can be modified by dragging the column separator to the left or right. The cursor changes to indicate that it can be moved horizontally and vertical line is shown in the ruler: 

    Resizing columns generates an On After Edit form event.

    To resize a column, click on the column separator and drag it to the left or right. Miniumum column size is 8pt. If the adjacent column on the right reaches the minimum size, all columns on the right will be moved. If the first column or an adjacent column to the left reaches the minimum size, no further resizing can occur in that direction.

    If you press the Shift key while resizing a column, the size of the adjacent column on the right will not be modified.

    Note: The Enterable property must be enabled for the SapphireOne Write Pro document to allow column resizing.

    Table Pagination  

    When displayed in Page or Draft mode (or the context of a document printing), SapphireOne Write Pro tables can split:

    • automatically, if the table height is greater than the available page/column height,
    • depending on page/column breaks set by programming or by the user.

    Tables only split between rows (paragaphs inside are never broken). 

    Note: The table pagination is dynamically updated if the orientation or column number are modified.

    Table pagination can be controlled by programming or by the user. Available actions include:

    • inserting a page break in a table:
    • inserting a column break in a table:

    When a page break or a column break is inserted through a standard action or the contextual menu, it is added before the selected contents: the first row of the selection is moved at the beginning of the next page or column. For example:

     ===> 

    Note: Tables cannot be broken in different sections. Inserting a section break in a table will move the whole table to the new section.

    Printing SapphireOne Write Pro Documents

    SapphireOne Write Pro documents can be printed in two ways:

    • As parts of SapphireOne forms
    • As independent documents

    Printing Documents in SapphireOne Forms  

    You can print SapphireOne Write Pro embedded objects as part of any kind of SapphireOne form (project, table, input, or output) using standard SapphireOne printing commands such as PRINT SELECTION or PRINT RECORD

    The standard Print Variable Frame option is also supported(*) for SapphireOne Write Pro areas, allowing you to manage size during printing. When this option is checked, the margins (outside and inside) and top border are only applied to the first page, and the margins (outside and inside) and bottom border are only applied to the last page. Pagination properties of the document are ignored: widow and orphan control is disabled and page breaks are not applied (these properties are only used for page rendering on screen, or for standalone printing of the document). When the Print Variable Frame option is selected, only objects located above the form area are printed. For more information about this option, refer to “Print Variable Frame” in the Design Reference manual.

    (*) The Print object and Print form commands are not compatible with this option. 

    View Mode for Printing  

    Regardless of the View mode set for the SapphireOne Write Pro area (see Configuring View properties), it is always printed as in the Embeddedmode when you use a SapphireOne printing command such as Print form. In this case, the following Appearance settings are not taken into account for the SapphireOne Write Pro form objects: Page view mode (always “Embedded”), Show headers, Show footers, Show page frame (always “No”), Show hidden characters (always “No”). 

    Example  

    The following example shows the effect of the Print Variable Frameoption on a SapphireOne Write Pro area embedded in the default output form. The following code is executed: ALL RECORDS([Movies])
     ORDER BY([Movies]Title)
     PRINT SELECTION([Movies])

    • Here is the result with the Print Variable Frame option unchecked (off):
    • Here is the result with the Print Variable Frame option checked(on):


      (Sample text source: Wikipedia)

    Printing Independent Documents

    Starting with SapphireOne v15 R5, SapphireOne Write Pro includes printing features allowing you to print independent SapphireOne Write Pro documents as well as to control standard printing options such as the format, orientation, or page numbers.

    SapphireOne Write Pro Commands

    Basically, two commands handle the SapphireOne Write Pro printing features: WP PRINT and WP USE PAGE SETUP.

    • WP PRINT launches a print job for a SapphireOne Write Pro document or adds the document to a current print job.
    • WP USE PAGE SETUP modifies the current printer page settings based on the SapphireOne Write Pro document attributes for page size and orientation.

    Note: On machines with Windows 7 or Windows Server 2008 R2, make sure that the Platform Update for Windows 7 has been installed so that the printing features are supported.

    Regular SapphireOne Commands  

    The following SapphireOne commands support SapphireOne Write Pro printing features:

    • SET PRINT OPTION and GET PRINT OPTION: All options are supported for SapphireOne Write Pro documents printed by WP PRINT. For Paper option and Orientation option, you may find it more efficient to call WP USE PAGE SETUP in order to easily synchronize these attributes with the SapphireOne Write Pro document settings. The Page range option (15) allows you to specify the page range to print. 
    • PRINT SETTINGS: Defines print settings for the current printer; if WP PRINT is called afterwards, it takes any print settings modified by means of the Print Settings dialog boxes into account (except for margins, which are always based on the SapphireOne Write Pro document).
    • OPEN PRINTING JOB and CLOSE PRINTING JOBWP PRINT can be called between these commands in order to insert one or more SapphireOne Write Pro documents into a single print job.

    Importing SapphireOne Write Documents    

    One of the main features of the new SapphireOne Write Pro object is the ability to import and convert existing SapphireOne Write documents. This will allow you to migrate applications that currently rely on the SapphireOne Write plug-in.

    Compatibility notes: 

    • Only SapphireOne Write documents of the last generation (“SapphireOne Write v7”) are supported.
    • Copying-pasting from a SapphireOne Write document to a SapphireOne Write Pro area is not supported for the moment. A SapphireOne Write document can only be imported using SapphireOne Write Pro language commands.
    • Carriage returns (CR) in formulas behave differently in SapphireOne Write and SapphireOne Write Pro. In SapphireOne Write, they are always interpreted as paragraph breaks, whereas in SapphireOne Write Pro they are interpreted as line breaks by default. To maintain CR in formulas as paragraph breaks in imported SapphireOne Write documents, after conversion use:
       WP SET ATTRIBUTES(wp;wk break paragraphs in formulas;wk true)
      For more information, see Managing formulas.

    How to Import a SapphireOne Write Document  

    SapphireOne Write Pro objects offer two ways to import SapphireOne Write documents:

    • For SapphireOne Write files stored on disk, you use the WP Import document command, 
    • For SapphireOne Write areas stored in BLOB fields, you use the WP Newcommand.

    For more information, please refer to the description of these commands.

    Which Properties Will be Recovered From SapphireOne Write?  

    To facilitate your migration from the SapphireOne Write plug-in to SapphireOne Write Pro, we want to support as many SapphireOne Write features as possible in SapphireOne Write Pro objects.

    This paragraph lists the SapphireOne Write plug-in properties that are currently recovered in a SapphireOne Write Pro area after an import using the  WP Import document or WP New commands. 

    Note however that a few differences can be seen, which are not considered as bugs. This is due, for example, to the default font used in SapphireOne Write Pro for bullets, or small conversions in the Underline type. 

    Document Info  

    SapphireOne Write plug-in SapphireOne Write Pro
    Creation date & time Available
    Modification date & time Available
    Locked Not available (use read-only object property)
    Title Available
    Subject Available (only plain text)
    Author Available
    Company Available
    Notes Available

    Document View Parameters  

    SapphireOne Write plug-in SapphireOne Write Pro
    View page mode Not imported (use Document/Page view mode in the context menu)
    View rulers Not imported (use object property)
    View frames Not imported (use object property)
    View header Not imported (use object property)
    View footer Not imported (use object property)
    View first page header Not available
    View first page footer Not available
    View pictures Not available
    View HScrollbar Not imported (use hor. scrollbar object property)
    View VScrollbar Not imported (use vert. scrollbar object property)
    View invisible characters Not imported (use object property)
    View references Not imported (use ST SET OPTIONS)
    View column separators Available (starting with v17)
    View H Splitter Not available
    View V Splitter Not available
    View Wysiwyg Not available
    View zoom Not imported (use Document/Zoom in the context menu)

    Document Parameters  

    SapphireOne Write plug-in SapphireOne Write Pro
    Unit Not imported (use Document/Measurement unit in the context menu)
    Language Not available
    Count of columns Available (starting with v17)
    Column spacing Available (starting with v17)
    Widows & orphans Available
    Default tab Available
    Leading tab Available
    URL color Not available
    URL visited color Not available

    Note: SapphireOne separator (as returned by GET SYSTEM FORMAT) is used as decimal separator for decimal tabs. You can change this parameter using the WP SET ATTRIBUTES command. 

    Document Pagination Parameters  

    SapphireOne Write plug-in SapphireOne Write Pro
    Page width Available
    Page height Available
    First page number Available
    First page header & footer are different Available
    Left & right page header & footer are different Available 
    Page binding Available
    Opposite pages Available
    Page margins Available
    Header top margin Available
    Header bottom margin Available
    Footer top margin Available
    Footer bottom margin Available 
    First page top margin Available 
    First page bottom margin Available 
    Header first page top margin Available
    Header first page bottom margin Available
    Footer first page top margin Available
    Footer first page bottom margin Available
    First page is right Available

    Document Printing Parameters  

    SapphireOne Write plug-in SapphireOne Write Pro
    Kind of paper Not available
    Landscape Not available
    Width Not available
    Height Not available
    User margins Not available
    Scale Not available
    X resolution Not available
    Y resolution Not available

    Images  

    Compatibility notes: 

    • Picture display modes are automatically imported as of SapphireOne Write Pro v19 R2, using WP Import document. You can restore the previous behavior (all images are scaled to fit) using the importDisplayMode attribute. 
    • On Windows, images having the Mac OS PICT format are imported but cannot be rendered in SapphireOne Write Pro. If you import a document containing images of this type, you need to convert them to another format. Support of PICT format has been removed since SapphireOne v18 and can no longer be used.
    SapphireOne Write plug-in SapphireOne Write Pro
    X (left) (& position :absolute) (for images in page only)
    Y (top) (& position :absolute) (for images in page only)
    Width Available
    Height Available
    Page number Available (starting with v16 R6)
    Behind Available (starting with v16 R6)
    Not in first page Available (starting with v16 R6)
    Viewport mode (scale to fit, etc.) Available
    Is expression Available for inline pictures (starting with v16 R5)
    Keep size Not imported (automatic in SapphireOne Write Pro)

    Character Properties  

    SapphireOne Write plug-in SapphireOne Write Pro (span properties)
    Italic Available
    Bold Available
    Strikeout Available
    Underline Available
    Shadow Available
    Exponent (superscript or subscript) Available
    Capitals (uppercase or small uppercase) Available
    Font Family Available
    Font Size Available
    Text Color Available
    Text Back Color Available
    Underline Color Available
    Strikeout Color Available
    Shadow color Available
    User property Not available
    Spell checking (syntax & grammar on or off) Not imported (area property)
    Appearance Not available
    Style sheet Available (starting with SapphireOne v18)

    Paragraph Properties  

    SapphireOne Write plug-in SapphireOne Write Pro
    Justification Available
    Interline Available
    Bullet Available
    Left margin Available
    Right margin Available
    Text indent Available
    Border line style Available
    Border line color Available
    Border back color Available
    Left border Available
    Right border Available
    Top border & top inside border Available
    Bottom border & bottom inside border Available
    Border spacing Available
    Style Sheet Available
    Tabulations Available

    SapphireOne Write plug-in SapphireOne Write Pro
    URL link Available (*)
    SapphireOne method link Available (**) (starting with v17 R5)
    Open document link Available (converted to a local file URL)
    • (*) Starting with SapphireOne v16 R4, URL links are converted to editable attributes. For more information, please refer to Link commands.
    • (**) You need to adapt parameters received within the called methods:
      ParametersSapphireOne Write plug-inSapphireOne Write Pro$1Longint – SapphireOne Write area referenceText – SapphireOne Write Pro area name$2Text – Link labelObject – Link description:
      • .method – Link’s method name. Must be be allowed with the SET ALLOWED METHODS command. 
      • .parameter – User parameter value passed to the method (if used)
      • .range – Range of the link’s label. See Range handling commands

      $3Longint – User parameter (methodRef)- 

    SapphireOne Expressions  

    SapphireOne Write plug-in SapphireOne Write Pro
    SapphireOne expression Available*
    Date & Time Available
    HTML expression Not available**
    RTF expression Not available

    *Use the WP SET ATTRIBUTES command with the wk break paragraphs in formulas attribute to transform CR returned by formulas into paragraph breaks in the imported document (line breaks by default). (See Managing formulas

    **can be imported as text between ##htmlBegin## and ##htmlEnd## tags if you use the wk import html expressions as textconstant.

    Text Data  

    SapphireOne Write plug-in SapphireOne Write Pro
    Main text data Available
    Header text data Available
    Footer text data Available

    Managing Formulas  

    Overview  

    SapphireOne Write Pro documents can contain references to SapphireOne formulas such as variables, fields, expressions, project methods, or SapphireOne commands. Specific information such as the page number can also be referenced through formulas (see Inserting document and page expressionsbelow).

    Inserting formulas in SapphireOne Write Pro areas is done with the WP INSERT FORMULA command and can be read using the WP Get formulascommand. They are also returned by the WP Get text command. 

    Formulas are evaluated:

    • when they are inserted in a form object which displays computed values
    • when the SapphireOne Write Pro object is loaded in a form object which displays computed values
    • when the WP COMPUTE FORMULAS command is called
    • when they are “frozen” using the WP FREEZE FORMULAScommand (if not already computed)
    • before printing (if not already computed)
    • before exporting to .docx (if formula can’t be mapped with MS Word formulas)
    • when the standard actions to freeze, print, export, or compute formulas are called. See Standard actions

    Formulas are not evaluated when a document is loaded (using WP NewWP INSERT DOCUMENT or wpArea:=[table]field):

    • if the document is only offscreen,
    • if the document is displayed onscreen but the form object only shows references.

    Formulas become static values if you call the WP FREEZE FORMULAScommand (except for page number and page count, see below).

    Compatibility NoteHandling expressions using the ST INSERT EXPRESSIONST Get expressionST COMPUTE EXPRESSIONS, and ST FREEZE EXPRESSIONS commands is deprecated, however it is still supported in SapphireOne Write Pro for compatibility.  

    Example  

    You want to replace the selection in a SapphireOne Write Pro area with the contents of a variable: C_TEXT(fullName)
     C_OBJECT($sel)
     fullName:="John Smith"
     $sel:=WP Selection range(SapphireOneWPArea)
     Case of
        :(Form event code=On Clicked)
           WP INSERT FORMULA($sel;Formula(fullName);wk replace)
     End case

    Inserting Document and Page Formulas  

    You can insert special expressions related to document attributes or page attributes in any document area (body, header, footer) using the WP INSERT FORMULA command.

    Formula syntax Type Description
    This.title Text Title defined in wk title attribute 
    This.author  Text Author defined in wk author attribute 
    This.subject  Text Subject defined in wk subject attribute 
    This.company Text  Company defined in wk company attribute 
    This.notes Text  Notes defined in wk notes attribute 
    This.dateCreation Date  Date creation defined in wk date creation attribute 
    This.dateModified Date  Date modified defined in wk date modified attribute 
    This.pageNumber (*) Longint Page number as it is defined: 
    from the document start (default) orfrom the section page start if it is defined by section page start. This formula is always dynamic, it is not affected by the WP FREEZE FORMULAS command.  
    This.pageCount (*) Longint  Page count: total count of pages. 

    This formula is always dynamic, it is not affected by the WP FREEZE FORMULAS command.

    This.document Object SapphireOne Write Pro document

    (*) ImportantThis.pageNumber and This.pageCount must be used only directly in a SapphireOne Write Pro formula (they must be present in the formula.source string). They will return incorrect values if they are used by the SapphireOne language within a method called by the formula. However, they can be passed as parameters to a method called directly by the formula:

    • This will work: « formatNumber(This.pageNumber) »
    • This will NOT work: « formatNumber » with formatNumbermethod processing This.pageNumber.

    For example, to insert the page number in the footer area: $footer:=WP Get footer(SapphireOneWP;1)
     WP INSERT FORMULA($footer;Formula(This.pageNumber);wk append)
      //Using Formula(myMethod) with myMethod processing This.pageNumber
      //would not work correctly

    Compatibility Note: Existing $wp_ variables in documents from versions prior to SapphireOne v18 R2 are still supported and evaluated. 

    Inserting Date and Time Formulas  

    Date

    When the Current date command, a date variable, or a method returning a date is inserted in a formula, it will automatically be transformed into text using system date short format. 

    Time

    When the Current time command, a time variable, or a method returning a time is inserted in a formula, it must be enclosed within a String command because time type is not supported in JSON. Consider the following examples of formulas:  // This code is the best practice
     $formula1:=Formula(String(Current time)) //OK 
     
      // This code will work but is usually not recommended, except after "Edit formula"
     $formula2:=Formula from string("String(Current time)") //OK
     
      // Wrong code because time values would be displayed as a longint for seconds (or milliseconds), not as a time
     $formula3:=Formula from string("Current time") //NOT valid
     $formula4:=Formula(Current time) //NOT valid

    Support of Virtual Structure  

    Table and field expressions inserted in SapphireOne Write Pro documents support the virtual structure definition of the database. The virtual structure exposed to formulas is defined through SET FIELD TITLES(…;*) and SET TABLE TITLES(…;*) commands. 

    When a virtual structure is defined:

    • references to expressions containing fields display virtual names when the SapphireOne Write Pro document shows references and not values. 
    • WP Get text returns virtual structure names if wk expressions as source option is set in expressions parameter. 
    • WP INSERT FORMULA ignores the virtual structure and always expects real table/field names

    Note: When a document is displayed in “display expressions” mode, references to tables or fields that do not belong to the virtual structure are displayed with “?” characters, for example [VirtualTableName]? when the field is not defined in the virtual structure.

    Using SapphireOne Write Pro Standard Actions

    Overview  

    The user interface of SapphireOne Write Pro areas can be handled through a wide set of standard actions. Standard actions can be assigned to:

    • menu commands, available through the menu bar or the Dynamic pop up menu command
    • list items, available through pop-up/drop-down lists or hierarchical pop-up menus,
    • buttons, check boxes,
    • or executed by the INVOKE ACTION command.

    When assigned to interface objects, standard actions handle the activation/disabling of the object depending on the context. For more information, please refer to the Standard actions section.

    Two kinds of actions are available for SapphireOne Write Pro areas:

    • SapphireOne Write Pro specific actions, that can be used only with SapphireOne Write Pro areas,
    • Other actions, including fonts, expressions, spell check, and editing actions, that can be used with SapphireOne Write Pro areas and other SapphireOne areas (see Standard actions).

    SapphireOne Write Pro Actions  

    The following standard actions are available with SapphireOne Write Pro areas.

    Notes:

    • Actions that display an automatic menu/list can only be attached to menu commands, pop-up/drop-down lists or hierarchical pop-up menus objects (see Submenu).
    • Check boxes and 3D check boxes should be associated with status actions, such as “section/differentFirstPage” or “visibleHorizontalRuler”. Three-states option is supported with standard check boxes only.
    • A section action status is always equal to the selected section actual status (inherited status if attribute is inherited from parent section or from default attribute) as it must reflect the selected section status (the status which is applied currently to the section). However, modifying a section attribute with a standard action will only override the selected section attribute.
    • Submenu: When used without any parameters and associated to a menu command, a pop-up/drop-down list or a hierarchical pop-up menu object, these actions display an automatic submenu/list. For example, if you assign the “backgroundColor” action to a menu command, selecting this menu command at runtime will display the Background color submenu items. If you assign the “zoom” action to a hierarchical pop-up menu, it will automatically contain a list of predefined zoom values. Note that these actions cannot be assigned to buttons.
    • showDialog: Adding the “/showDialog” string to the action name allows the display of the associated standard dialog box for the action. For example, you can use “paragraph/styleSheet/showDialog” to open the input dialog allowing the entry of a new stylesheet name. 
     Action Constant(if any)  Syntax  Availablewith  Description 
    anchorHorizontalAlign  wk anchor horizontal align  anchorHorizontalAlign?value={left | center | right}  Image,
    Submenu
    Defines the horizontal alignment of the image, relative to the anchorOrigin for images in page, or to the layout box for images in embedded mode. This action will reset the horizontal offset to 0. (not enabled for inline images). 
    anchorLayout wk anchor layout anchorLayout?value={inline | front | behind} Image,
    Submenu
    Defines the anchor layout type for an image. May be used to transform an inline image to an anchored image in front of or behind text, or the reverse. 

    Note: if an image is moved from front/behind text to inline, the image is inserted at the beginning of the current selected text.

    anchorOrigin wk anchor origin anchorOrigin?value={paper-box | header-box | footer-box} Image,
    Submenu
    Defines the area relative to the absolute position of an anchored image. If an image is relative to the header-box/footer-box which is not visible on a page, the image is not displayed. This action will reset horizontal and vertical offsets to 0.

    Page mode only, not enabled for inline images.

    anchorPage wk anchor page anchorPage?value={all | current | currentSubSection} Image,
    Submenu
    Defines the page(s) where the selected image is displayed (not enabled for inline images).

    Page mode only.

    anchorSection wk anchor section anchorSection?value={all | current} Image,
    Submenu
    Defines the section(s) where the selected image is displayed. (not enabled for inline images).

    Page mode only.

    anchorVerticalAlign wk anchor vertical align anchorVerticalAlign?value={top | center | bottom} Image,
    Submenu
    Defines the vertical alignment of the image, relative to the anchorOrgin for images in page, or to the layout box for images in embedded mode. This action will reset the vertical offset to 0 (not enabled for inline images).
    avoidPageBreakInsideEnabled wk page break inside avoidPageBreakInsideEnabled Paragraph Allows/disallows page break inside paragraphs.
    background    {doc | paragraph | image | section | header | footer | table | row | column | cell}/background Document,
    Paragraph,
    Image,
    Section,
    Header,
    Footer, 
    Table,
    Row,
    Column,
    Cell,
    Submenu
    For menu commands only. Default submenu for all background attributes.
    backgroundClip wk background clip {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundClip?value={paper-box | border-box | padding-box | content-box} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background clipping box (default target is paragraph). Paper-box targets document and section only.
    backgroundColor wk background color {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundColor?value={<Css_color> | transparent} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu,
    showDialog
    Changes target background.
    backgroundDisplayMode wk background display mode {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundDisplayMode?value=scaledToFit | truncated | truncatedCentered | proportional | proportionalCentered | replicated | replicatedCentered Document,
    Paragraph,
    Image,
    Section,
    Header,
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Sets the display mode of images used as background.
    backgroundImage wk background image {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundImage?value=none Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu,
    showDialog
    Clears target background image. (default target is paragraph)
    backgroundOrigin wk background origin {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundOrigin?value={paper-box | border-box | padding-box | content-box} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background image origin box (default target is paragraph). Paper-box targets document and section only.
    backgroundPositionH wk background position horizontal {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundPositionH?value={left | right | center} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background image horizontal alignment (default target is paragraph).

    Ex: paragraph/backgroundPositionH?value=left

    backgroundPositionV wk background position vertical {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundPositionV?value={top | bottom | center} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background image vertical alignment (default target is paragraph).

    Ex: paragraph/backgroundPositionV?value=top

    backgroundRepeat wk background repeat {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundRepeat?value={no-repeat | repeat | repeat-x | repeat-y} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background image repeat mode. (default target is paragraph)
    backgroundSizeH wk background width {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundSizeH?value={<Css_length> | <Css_percentage> | auto | cover | contain} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background image width (default target is paragraph).

    Ex: paragraph/backgroundSizeH?value=100%. section/backgroundSizeH?value=cover

    backgroundSizeV wk background height {doc | paragraph | image | section | header | footer | table | row | column | cell}/backgroundSizeV?value={<Css_length> | <Css_percentage> | auto} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target background image height (default target is paragraph).

    Ex: paragraph/backgroundSizeV?value=50%. Ex: section/backgroundSizeV?value=40pt

    bookmark   bookmark?index=<number> Submenu Selects the Nth bookmark.

    Ex: bookmark?index=2 // selects the second bookmark

    borderCollapse   borderCollapse Paragraph Collapses selected paragraph borders and interior margins.
    borderColor wk border color {doc | paragraph | image | section | header | footer | table | row | column | cell/}{inside | outside/}{borderColor | borderColorLeft | borderColorRight | borderColorTop | borderColorBottom | borderColorLeftRight | borderColorTopBottom}?value=<Css_color> Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu,
    showDialog
    Changes target border color (default target is paragraph).

    Ex: paragraph/borderColorLeft?value=green

    borderRadius wk border radius {doc | paragraph | image | section | header | footer}/borderRadius?value=<Css_length> Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Submenu
    Changes target border radius (default target is paragraph).

    Ex: paragraph/borderRadius?value=4pt

    borders wk border color {doc | paragraph | image | section | header | footer | table | row | column | cell/}{inside | outside/}borders Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer, 
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Default submenu for target borders.
    borderStyle wk border style {doc | paragraph | image | section | header | footer | table | row | column | cell/}{inside | outside/}{borderStyle | borderStyleLeft | borderStyleRight | borderStyleTop | borderStyleBottom | borderStyleLeftRight | borderStyleTopBottom}?value={none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target border style (default target is paragraph).

    Ex: paragraph/borderStyleLeft?value=double. Ex: outside/borderStyle?value=solid //set selected paragraphs exterior borders to style solid. Ex: inside/borderStyle?value=none //remove selected paragraphs interior borders

    borderWidth wk border width {doc | paragraph | image | section | header | footer | table | row | column | cell/}{inside | outside/}{borderWidth | borderWidthLeft | borderWidthRight | borderWidthTop | borderWidthBottom | borderWidthLeftRight | borderWidthTopBottom}?value=<Css_length> Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Row,
    Column,
    Cell,
    Submenu
    Changes target border width (default target is paragraph).

    Ex: paragraph/borderWidthLeft?value=4pt

    columnCount wk column count {section/}columnCount?value={1<=number<=20} Document, Section,
    Submenu
    Number of columns in the current document and/or section. (default target is doc)

    Ex: section/columnCount?value=3

    columnRuleColor wk column rule color {section/}columnRuleColor?value={CSS color} Document,
    Section,
    Submenu,
    showDialog
    Color for the decorative line between document or section columns.

    Ex: columnRuleColor?value=”#FFFFFF”

    columnRuleStyle wk column rule style {section/}columnRuleStyle?value={none | dotted | dashed | solid | double | groove | ridge | inset | outset} Document,
    Section,
    Submenu
    Style for the decorative line between document or section columns.

    Ex: columnRuleStyle?value=”solid”

    columnRuleWidth wk column rule width {section/}columnRuleWidth?value={CSS length} Document,
    Section,
    Submenu
    Width of the decorative line between document or section columns.

    Ex: columnRuleWidth?value=”2pt”

    columns   {section/}columns Document,
    Section,
    Submenu
    Only for a menu item: creates automatically a complete Columns sub-menu with all column actions sub-menus (except insertColumnBreak)
    columnSpacing wk column spacing {section/}columnSpacing?value={CSS length} Document,
    Section,
    Submenu
    Space between two columns in the current document and/or section.

    Ex: columnSpacing?value=”1cm”

    deleteColumns   deleteColumns Table Deletes all selected columns.
    deleteRows   deleteRows Table Deletes all selected rows.
    deleteStyleSheet   {paragraph | image}/deleteStyleSheet?index={1<= number <= number of target style sheets} Paragraph,
    Image,
    Submenu
    Removes the Nth stylesheet from the stored stylesheets for the selected target (default target is paragraph). Menu item name is replaced at runtime with style sheet name.
    direction wk direction direction?value={ltr | rtl} Paragraph,
    Submenu
    Paragraph direction.
    doc   doc Document,
    Submenu
    Default submenu for document body layout (embedded mode attributes or default attributes for sections – but for margin which is reserved for embedded mode only).
    dpi wk dpi Modifies the dpi of the current view (independent of the document attribute wk dpi used internally for pixel conversion <-> points). Submenu Change view dpi.

    Ex: dpi?value=72

    fontStyleWrite   fontStyleWrite Submenu For menu commands only. Displays default font styles submenu for SapphireOne Write Pro.
    fontSubscript wk style sheet fontSubscript   Toggles subscript font attribute.
    fontSuperscript wk superscript fontSuperscript   Toggles superscript font attribute.
    footer   footer Submenu Displays the Footer submenu.
    footer/remove   footer/remove Footer Removes the selected footer.
    formulaHighlight wk formula highlight formulaHighlight?value={values | references | always | never} Document, 
    Submenu
    Formula highlight mode for the document. Can be used with a dropdown menu or a button
    formulaHighlightColor wk formula highlight color formulaHighlightColor?value=<Css_color> Document, 
    Submenu,showDialog
    Formula highlight color for the document
    formulaHighlightReferences   formulaHighlightReferences Document Toggles formula references highlighting. Can be used with a check box or a menu item
    formulaHighlightValues   formulaHighlightValues Document Toggles formula values highlighting. Can be used with a check box or a menu item
    header   header Submenu Displays the Header submenu.
    header/remove   header/remove Header Removes the selected header.
    height wk height {image | row}/height?value={<Css_length> | auto} Image,
    Row,
    Submenu
    Target height.

    Ex: image/height?value=50pt. For image/width, see width.

    Ex: row/height?value=12pt

    htmlWYSIWIGEnabled wk html wysiwyg htmlWYSIWIGEnabled Document Toggles between html wysiwyg mode.
    image wk image image Image,
    Submenu
    Displays image layout submenu.
    image/displayMode wk image display mode image/displayMode?value=scaledToFit | truncated | truncatedCentered | proportional | proportionalCentered | replicated | replicatedCentered Image,
    Submenu
    Sets the display mode of anchored and inline images.

    Ex: image/displayMode?value=scaledToFit

    image/verticalAlign wk vertical align image/verticalAlign?value={top | middle | bottom | baseline | super | sub} Image,
    Submenu
    Image vertical alignment.

    Ex: image/verticalAlign?value=super

    insertColumnBreak wk column break insertColumnBreak Paragraph Inserts a column break at the selection.
    insertColumnToTheLeft   insertColumnToTheLeft Table Inserts a column to the left of the first selected column(s).
    insertColumnToTheRight   insertColumnToTheRight Table Inserts a column to the right of the last selected column(s).
    insertContinuousSectionBreak wk continuous section break insertContinuousSectionBreak Paragraph Inserts a continuous section break at the selection.
    insertImage   insertImage   Opens a picture selection dialog box and inserts the selected picture (if any) as a character in the area.
    insertPageBreak   insertPageBreak Paragraph Inserts a page break at the selection.
    insertRowAbove   insertRowAbove Table Inserts a row above the selected row(s).
    insertRowBelow   insertRowBelow Table Inserts a row below the selected row(s).
    insertSectionBreak   insertSectionBreak Paragraph Inserts a section break at the selection.
    insertSoftHyphen   insertSoftHyphen   Inserts a soft hyphen at the cursor position.
    lineHeight wk line height lineHeight?value={<Css_length> | <Css_percentage>} Paragraph,
    Submenu
    Paragraph line height.

    Ex: lineHeight?value=120%

    listStartNumber wk list start number listStartNumber?value={<number> (longint) | auto} Paragraph,
    Submenu
    List start number.
    Ex: listStartNumber?value=10
    listStyleImage wk list style image listStyleImage/showDialog Paragraph,
    showDialog
    Opens a file dialog to choose a image to display as list style bullet; it will set also list style type to disc – style to be used if image is not found.
    listStyleType wk list style type listStyleType?value={none | disc | circle | square | hollow-square | diamond | club | decimal | decimal-leading- zero | lower-latin | lower-roman | upper-latin | upper-roman | lower-greek | decimal-greek | armenian | georgian | hebrew | hiragana | katakana | cjk-ideographic} Paragraph,
    Submenu
    Paragraph list style type.
    margin wk margin {doc | paragraph | image | section | header | footer | table/}{inside | outside/}{margin | marginLeft | marginRight | marginTop | marginBottom | marginLeftRight | marginTopBottom}?value={<Css_length> | auto} Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Table,
    Submenu
    Changes target margin (default target is paragraph).

    Ex: margin?value=4pt //sets all paragraph margins to 4pt.

    Ex: outside/margin?value=4pt //set exterior paragraph margins to 4pt.

    Ex: doc/marginLeft?value=1cm //sets left margin to 1cm for the document as used in embedded mode.

    Ex: section/marginLeft?value=1cm //sets left margin to 1cm for the pages of the first selected section

    merge   merge Paragraph Merges paragraphs.
    minHeight wk min height {paragraph | image}/minHeight?value=<Css_length> Paragraph,
    Image,
    Submenu
    Target min height (default target is paragraph).

    Ex: paragraph/minHeight?value=50pt

    minWidth wk min width {paragraph | image}/minWidth?value=<Css_length> Paragraph,
    Image,
    Submenu
    Target min width (default target is paragraph).

    Ex: paragraph/minWidth?value=50pt

    moveToBack   moveToBack Image Moves image to the back. (not enabled for inline images)
    moveToFront   moveToFront Image Moves image to the front. (not enabled for inline images)
    newLineStyleSheet wk new line style sheet newLineStyleSheet?index={1<=number<=number of paragraph stylesheets | newLineStyleSheet?value=auto Paragraph,
    Submenu
    Selected paragraph elements will use Nth stylesheet as stylesheet to use for new paragraphs created on Return or while splitting paragraphs; If value=auto, new paragraphs will use the same stylesheet (default). (menu item name is replaced at runtime with stylesheet name)
    padding wk padding {doc | paragraph | image | section | header | footer | column | row| cell/}{inside | outside/}{padding | paddingLeft | paddingRight | paddingTop | paddingBottom | paddingLeftRight | paddingTopBottom }?value=<Css_length> Document,
    Paragraph,
    Image,
    Section,
    Header, 
    Footer,
    Row,
    Column,
    Cell,
    Submenu
    Changes target padding. (default target is paragraph)
    pageMode   pageMode?value={embedded | page | draft} Submenu Changes view mode.

    Ex: pageMode?value=page

    pageOrientation wk page orientation {section/}pageOrientation?value={landscape | portrait} Section,
    Submenu
    Changes document or first selected section page orientation (if section is not specified, it will apply to all sections otherwise to the first selected section).

    Ex: pageOrientation?value=portrait //change orientation to portrait for the whole document.

    Ex: section/pageOrientation?value=landscape //change orientation to landscape for the first selected section

    pageSize wk page size pageSize?index=<number> Submenu Changes document page size: number is Nth page size in the list of available pages sizes in the current printer.

    Ex: pageSize?index=1

    paragraph   paragraph Paragraph,
    Submenu
    Default submenu for paragraph layout.
    print   print Document Prints document as rendered in page mode with view settings of the focused SapphireOne Write Pro area.
    refreshImages   refreshImages Image Reloads images from the network for images with URLs.
    removeSoftHyphens   removeSoftHyphens   Removes all soft hyphens in the current selection (if the selection is empty, removes soft hyphen before or after the caret if any)
        section Section,
    Submenu
    Default submenu for page layout for the first selected section.
    section/differentFirstPage   section/differentFirstPage Section Section has different first page or not.
    section/differentLeftRightPages   section/differentLeftRightPages Section Section has different left and right pages or not.
    section/name/showDialog   section/name/showDialog Section,
    showDialog
    Displays a dialog allowing to enter the first selected section name.
    section/reset   section/reset Section Resets all first selected section attributes to default attributes – which are inherited from doc attributes for background, border and padding (same as for embedded mode) and 2.5cm for page margins. First selected section column properties are also removed (so only default section properties will apply).
    split   split Paragraph Splits paragraphs.
    styleSheet wk style sheet {paragraph | image}/styleSheet?value={1<=number<=number of target style sheets} Paragraph,
    Image,
    Submenu,
    showDialog
    Applies Nth stylesheet to the selected target elements. With dialog, new stylesheet will use current attributes from the first selected target. (default target is paragraph)

    Ex: styleSheet?value=1 //apply first paragraph style sheet to the selected paragraphs and set it as paragraph stylesheets.

    styleSheets   {paragraph | image}/styleSheets Paragraph,
    Image,
    Submenu
    Default submenu for editing target stylesheets.
    tabDecimalSeparator wk tab decimal separator tabDecimalSeparator?value={point | comma | pointOrComma | system} Document,
    Submenu
    Defines the character used as decimal separator by decimal tabulations. 
    tableAlign wk table align tableAlign?value={left | center | right} 

    or

    table/tableAlign?value={left | center | right} 

    Table,
    Submenu
    Specifies horizontal alignment for a table.
    textAlign wk text align textAlign?value={left | right | center | justify | initial} Paragraph Paragraph text alignment (initial=use right for rtl or left for ltr direction).
    textIndent wk text indent textIndent?value=<Css_length> (may be negative) Paragraph,
    Submenu
    Paragraph text indentation (first line indentation).

    Ex: textIndent?value=2cm

    textLinethrough   textLinethrough Submenu For menu commands only. Linethrough submenu (with style and color).
    textLinethroughColor wk text linethrough color textLinethroughColor?value={<Css_color> | currentColor} Submenu,
    showDialog
    Ex: textLinethroughColor?value=red
    textLinethroughStyle wk text linethrough style textLinethroughStyle?value={none | solid | dotted | dashed | double | semi-transparent | word} Submenu Ex: textLinethroughStyle?value=dotted
    textShadow   textShadow Submenu For menu commands only. Default submenu for text shadow (with color and offset).
    textShadowColor wk text shadow color textShadowColor?value={<Css_color> | none} Submenu,
    showDialog
    Changes shadow status or color for characters.

    Ex: textShadowColor?value=green

    textShadowOffset wk text shadow offset textShadowOffset?value=<Css_length> Submenu Only length in pt is supported.

    Ex: textShadowOffset?value=2pt

    textTransform wk text transform textTransform?value={none | capitalize | uppercase | lowercase | small-uppercase} Submenu Formats text.

    Ex: textTransform?value=capitalize

    textUnderline   textUnderline Submenu For menu commands only. Underline submenu (with style and color)
    textUnderlineColor wk text underline color textUnderlineColor?value={<Css_color> | currentColor} Submenu,
    showDialog
    Ex: textUnderlineColor?value=red
    textUnderlineStyle wk text underline style textUnderlineStyle?value={none | solid | dotted | dashed | double | semi-transparent | word} Submenu Ex: textUnderlineStyle?value=dotted
    updateStyleSheet   {paragraph | image}/updateStyleSheet Paragraph,
    Image,
    Submenu
    Updates first selected target stylesheet with first selected target current attributes (default target is paragraph)
    userUnit wk layout unit userUnit?value={cm | mm | in | pt} Submenu Changes document layout unit (will be reflected on rulers).
    verticalAlign wk vertical align {paragraph | row | column | cell}verticalAlign?value={top | middle | bottom} Paragraph,
    Row,
    Column, 
    Cell,
    Submenu
    Paragraph vertical alignment.

    Ex: verticalAlign?value=top. The effect depends on the minHeight value of the paragraph.

    view   view Submenu For menu commands only. Default submenu for view settings.
    visibleBackground wk visible background visibleBackground Document Shows/hides background.
    visibleFooters wk visible footers visibleFooters Document Shows/hides footers.
    visibleHeaders wk visible headers visibleHeaders Document Shows/hides headers.
    visibleHiddenChars wk visible hidden characters visibleHiddenChars Document Shows/hides hidden characters
    visibleHorizontalRuler wk visible horizontal ruler visibleHorizontalRuler Document Shows/hides horizontal ruler.
    visiblePageFrames wk visible page frames visiblePageFrames Document Shows/hides page frames.
    visibleVerticalRuler wk visible vertical ruler visibleVerticalRuler Document Shows/hides vertical ruler (Page mode only).
    widowAndOrphanControlEnabled wk avoid widows and orphans widowAndOrphanControlEnabled Paragraph Toggles between widow and orphan control mode.
    width wk width {paragraph | image | column}/width?value=<Css_length> | auto Paragraph,
    Image,
    Column,
    Submenu
    Target width (default target is paragraph). Auto value not available for columns.

    Ex: image/width?value=50pt

    zoom wk zoom zoom?value={25% <= percentage in Css <= 400%} Document,
    Submenu
    Changes document view zoom.

    Ex: zoom?value=120%

    Other Actions  

    Several other standard actions are available in SapphireOne forms and can be used in SapphireOne Write Pro areas:

    Handling Pictures

    Background Pictures  

    Pictures can be set as the background of SapphireOne Write Pro documents and document elements (tables, paragraphs, sections, headers/footers, etc.).

    Here is an example showing two different ways a picture can be used as a document’s background:

    Background pictures can be set either programmatically or via the context menu. For more information, see the Background section in the Using a SapphireOne Write Pro area article.

    Background picture display can also be set either programmatically or via the context menu. Note that background display mode values actually define presets of background settings, as listed in the constant description:

    Constant Comment
    wk proportional When used as value of wk image display mode, the image is aligned at the top left of the content box, not replicated, scaled to fit the content box, and it keeps its aspect ratio. When used as value of wk background display mode, presets the following attributes:wk background width = “contain”wk background height = “auto”wk background repeat = wk no repeatwk background origin = wk padding boxwk background position horizontal = wk leftwk background position vertical = wk top
    wk proportional centered When used as value of wk image display mode, the image is centered in the content box, not replicated, scaled to fit the content box and it keeps its aspect ratio. When used as value of wk background display mode, presets the following attributes:wk background width = “contain”wk background height = “auto”wk background repeat = wk no repeatwk background origin = wk padding boxwk background position horizontal = wk centerwk background position vertical = wk center
    wk replicated When used as value of wk image display mode, the image is aligned at the top left of the content box, replicated, and keeps its original size. When used as value of wk background display mode, presets the following attributes:wk background width = “auto”wk background height = “auto”wk background repeat = wk repeatwk background origin = wk padding boxwk background position horizontal = wk leftwk background position vertical = wk top
    wk replicated centered When used as value of wk image display mode, the image is centered in the content box, replicated, and keeps its original size. When used as value of wk background display mode, presets the following attributes:wk background width = “auto”wk background height = “auto”wk background repeat = wk repeatwk background origin = wk padding boxwk background position horizontal = wk centerwk background position vertical = wk center
    wk scaled to fit When used as value of wk image display mode, the image is scaled to fit the content box and is not replicated.  When used as value of wk background display mode, modifies the following attributes:wk background width = “100%”wk background height = “100%”wk background repeat = wk no repeatwk background origin = wk padding boxwk background position horizontal = wk leftwk background position vertical = wk top
    wk truncated When used as value of wk image display mode, the image is aligned at the top left of the content box, not replicated, and it keeps its original size.  When used as value of wk background display mode, presets the following attributes:wk background width = “auto”wk background height = “auto”wk background repeat = wk no repeatwk background origin = wk padding boxwk background position horizontal = wk leftwk background position vertical = wk top
    wk truncated centered When used as value of wk image display mode, the image is centered in the content box, not replicated, and it keeps its original size. When used as value of wk background display mode, presets the following attributes:wk background width = “auto”wk background height = “auto”wk background repeat = wk no repeatwk background origin = wk padding boxwk background position horizontal = wk centerwk background position vertical = wk center 

    Adding Pictures  

    Adding pictures to a SapphireOne Write Pro document can be accomplished in multiple ways and depend on your needs:

    • to add a background picture, use the wk background image or wk background image url attribute with the WP SET ATTRIBUTEScommand
    • to add an inline picturei.e. inserted in the text flow just like a character, use the WP INSERT PICTURE or the ST INSERT EXPRESSION command
    • to add an anchored picture in the page (behind or in front of the text), use the WP Add picture command.

    The way you add a picture determines the layer it is positioned in, as illustrated in the diagram below: 

    Positioning and Displaying of Anchored Pictures  

    Anchored pictures are added with an absolute position, in front of/behind text, as well as anchored to the page or specific parts of a document (i.e., header, footer, sections). Setting an absolute position for a picture is accomplished with the WP Add picture and  WP SET ATTRIBUTEScommands. 

    Anchored picture positions can be modified with the following specific attributes and/or standard actions:
     

    Property (constant) Standard action
    wk anchor layout anchorLayout
    wk anchor horizontal offset
    wk anchor horizontal align anchorHorizontalAlign
    wk anchor vertical offset
    wk anchor vertical align anchorVerticalAlign
    wk anchor origin anchorOrigin
    wk anchor page anchorPage
    wk anchor section anchorSection
      moveToBack
      moveToFront

    All anchored pictures are displayed in the Page view mode only. They’re not displayed if:

    • they are anchored to a header or footer which is not visible;
    • the view mode is Draft;
    • they are centered or anchored to sections and the Show HTML WYSIWYG option is checked;
    • the “Show background” option is not selected.

    Picture Expressions  

    You can insert SapphireOne expressions that return pictures in your SapphireOne Write Pro areas. Expressions can be variables, fields, project methods, object attributes or collection elements.

    You can see an expression’s reference in the picture tip(*):

    (*)As there is no text associated with an anchored image, its expression reference cannot be displayed.

    All image attributes can be applied to picture expressions (wk image and wk image url attributes can only be read). Note however, that since pictures have specific attributes, SapphireOne Write Pro must evaluate the expression at least once to detect that its result is a picture and handle it as a picture expression. It means that when a picture expression is inserted with WP INSERT FORMULAWP COMPUTE FORMULAS must be called before setting any picture attributes.

    If the image resulting from the expression could not be computed or loaded, SapphireOne Write Pro displays the default black frame image:

    Note: As with other expressions, picture expressions are also impacted by the WP COMPUTE FORMULAS and WP FREEZE FORMULAS commands.

    Anchored Pictures  

    Anchored picture expressions are added with the WP Add picturecommand (without the second parameter), followed by a call to the WP SET ATTRIBUTES command with the wk image formula selector.

    Example: obImage:=WP Add picture(myDoc)
     WP SET ATTRIBUTES(obImage;wk image formula;Formula(m_buildPict))

    You can also insert picture expressions using WP SET ATTRIBUTES and wk image formula on existing anchored pictures.

    Compatibility Note: wk image expression can still be used to define picture expressions through text. However, it is recommended to use wk image formula and objects. 

    Calling the WP RESET ATTRIBUTES command with wk image formula is similar to calling WP FREEZE FORMULAS (on the entire document) in that the expression is cleared from the image attribute. However WP FREEZE FORMULAS computes the expression before clearing, whereas WP RESET ATTRIBUTES does not. If an expression has never been computed, the default black frame image will be displayed.

    Inline Pictures  

    Inline picture expressions are added with the WP INSERT FORMULAcommand.

    Examples:  //Insert a picture variable
     WP INSERT FORMULA(wpRange;Formula($vpict);wk prepend)
     
      //Insert a field
     WP INSERT FORMULA(wpRange;Formula([DOC]SamplePict);wk prepend)
     
      //Insert a SapphireOne method
     WP INSERT FORMULA(wpRange;Formula(M_ComputeChart);wk prepend)

    Picture Properties  

    All pictures have properties (attributes) such as height, width, borders, display mode, etc., that can be get or set via the SapphireOne Write Pro language (WP GET ATTRIBUTES and WP SET ATTRIBUTES) or standard actions.

    Picture Reference or Picture URL  

    You can work with picture references (picture variables, fields, expressions) or picture URLs (text representing a local or network address of the picture).

    Two sets of attributes allow you to define if you want to set or get picture reference or a picture URL:

    • wk image, wk background image, wk list style image: to set or to get picture references. 
      When you get a picture using one of these attributes, you receive a SapphireOne picture, no matter how the picture was defined.
    • wk image url, wk background image url, wk list style image url: to set or get picture URLs.
      When you get a picture using one of these attributes, you receive a text. If the picture was defined through a reference (e.g. a picture variable), you get a local URI followed by the image in Base64.

    Example: $range:=WP Get selection(WPArea) //get the picture selected by user
     $range:=WP Picture range($range) //create a range
     $url:="http://doc.4d.com/image/logo/poweredbySapphireOne_web_.jpg"
     
     WP SET ATTRIBUTES($range;wk image;$url) //set an image reference from a URL
     
      //get the image
     C_PICTURE(vPictureGet)
     WP GET ATTRIBUTES($range;wk image;vPictureGet) //vPictureGet contains an image
     C_TEXT(vPictureURLGet)
     WP GET ATTRIBUTES($range;wk image url;vPictureURLGet) //vPictureURLGet=$url

    Retrieving Pictures  

    The following commands can be used to return pictures:

    Deleting Pictures  

    You can remove inline and anchored pictures with: 

    Mouse/keyboard Actions  

    Pictures can be manipulated via the mouse or the keyboard. Available actions include:

    • SELECT
      • Pictures in the Front layer can be selected by clicking on them;
      • Background pictures can be selected by CTRL+ clicking on it (Windows) or COMMAND+clicking on it (Mac);
      • Only a single picture with an absolute position can be selected: multiple selection is not possible.
    • MOVE
      • Pictures can be moved and resized using the mouse; (inline images cannot be dragged outside the document).
    • INSERT
      • If pictures with an absolute position are pasted in Draft mode, they are displayed inline at the beginning of the current keyboard selection.
    • CUT/PASTE/COPY
      • Pictures can be copied to the clipboard, or cut/pasted while selected.
      • Pasting a picture with an absolute position in Page mode will paste the picture in the first selected page and anchor it to that page, no matter the original page anchoring settings; pasted pictures will retain their offsets, unless it is pasted into a different mode than the original (for instance if the picture is copied in Page mode and pasted in Embedded mode, the offsets are reset to 0).
    • DELETE -Pictures can be deleted while selected with the:
      • DELETE key, or
      • keyboard shortcut for the action Clear

     Importing and Exporting in .docx Format

    SapphireOne Write Pro can both import and export documents in the .docx format. This format is supported by word processing applications such as Microsoft Word.

    Compatibility note: Support for SapphireOne Write Pro documents imported or exported in .docx format is only certified for Microsoft Word 2010 and newer. Older versions, particularly Microsoft Word 2007, may not be able to open the documents.

    How to import .docx Format  

    Documents in .docx format can be imported into SapphireOne Write Pro with the WP Import document command. For more information, please refer to the description of this command.

    Behavioural Changes  

    While the majority of .docx settings are preserved, some settings are known to be either unsupported or behave differently in SapphireOne Write Pro. These are:

    Alignment / Layout  
    Setting Description
    Anchored text areas Anchored text areas are not supported. The content can be ignored or imported as inline text (option to set when using the WP Import document command).
    Paragraph layout Only Western text layouts are supported. Distributed, Thai and Asian paragraph styles are not supported.
    Page Size Different page sizes per section are not supported. Only the page size from the first section is imported.

    Background  
    Setting Description
    Watermark Not supported 

    Expressions  
    Setting Description
    MS Word equations Not supported. Data is not imported. 
    MS Word charts Not supported. Data is not imported. 

    Lists  
    Setting Description
    Hierarchical lists Multi-level lists are not supported. Multi-level lists are converted to a single level lists so list appearance and/or numbering may be different the 
    import operation.

    Pictures / Images  
    Setting Description
    DrawingML shapes Only simple DrawingML images (inline or anchored) are imported. Complex DrawingML shapes are not supported.
    VML shapes or images Not supported. VML is obsolete in MS Word and should not be used in documents created with MS Word 2010 or older.
    3D models Not supported, however the last rendered 2D image of the 3D model may be imported if present in the .docx.
    SmartArt Not supported.  

    References / Review  
    Setting Description
    Comments Not supported. Content is not imported. 
    Footnotes Not supported. Content is not imported. 

    Spacing  
    Setting Description
    “At least” line spacing Not supported. “At least” line spacing is converted to fixed (single) line spacing.
    Fit text Not supported. The normal SapphireOne Write Pro style is used.

    Tables  
    Setting Description
    Tables Contiguous tables do not merge automatically. Column or row span is not supported.

    Text  
    Setting Description
    Themes Text themes are not imported. If a color or font definition references a color or font in a theme, the last computed color or font will be used. Otherwise, the 
    color or font defined in the theme is used.

    Import Log  

    When importing .docx format into SapphireOne Write Pro, a log object is created and included within the imported document object. This object can be retrieved with the WP GET ATTRIBUTES command: $myDoc:=WP Import document("test.docx")
     if($myDoc#Null)
        C_OBJECT($log)
        WP GET ATTRIBUTES($myDoc;wk import log;$log)
     End if

    The import log object contains the following properties:

    Constant Comment
    wk import log Log object containing information about the .docx import operation. Properties are read-only and cannot be set: Property TypeDescriptionstatus TextImport status:
    successful – the document is imported into SapphireOne Write Pro failed – an empty SapphireOne Write Pro document is returneddeveloper CollectionCollection of message object(s) for SapphireOne Write Pro developers. [ ].typeTextThe kind of message logged:
    infowarningerror [ ].messageTextMessage about the import operation.user CollectionCollection of message object(s) for SapphireOne Write Pro users. [ ].typeTextThe kind of message logged:
    infowarning [ ].messageShortTextBrief message about the import operation. [ ].messageLongTextExtended message about the import operation. 

    How to Export in .docx Format  

    SapphireOne Write Pro objects offer two ways to export SapphireOne Write Pro documents in .docx format:

    For more information, please refer to the description of these commands.

    Behavioral Changes  

    While the majority of SapphireOne Write Pro settings are preserved, some settings are known to be either unsupported or behave differently in Microsoft Word. These are:

    Alignment / Layout  
    Setting Paragraphs Sections Images
    Anchoring In Microsoft Word, anchored images are positioned relative to the top left origin of the page and first paragraph. This could result in images being displayed in different locations than desired due to text layout differences between SapphireOne Write Pro and Microsoft Word.
    Vertical align Not supported by Microsoft Word (all items will be top-aligned) Not supported for inline images (all items will be baseline)

    Background  
    Setting Paragraphs Sections Images
    Background clipping Not supported by Microsoft Word (background color fills entire paragraph, not including borders and margins) Not supported by Microsoft Word (background clipping will be equal to the padding box)
    Background image Not supported by Microsoft Word Different background pictures/colors not supported by Microsoft Word (converted to anchored images or shapes) Microsoft Word allows either a background color or a background image. If a background image is defined, the background color will be “transparent”.
    Background image repeat Horizontal or vertical tiles are converted to full tiles in Microsoft Word Horizontal or vertical tiles are converted to full tiles in Microsoft
    Background origin Origin box is converted to the same value as background clipping box. Not supported by Microsoft.

    Borders  
    Setting Paragraphs Sections Images
    Border color Different border colors for each border line is not supported by Microsoft Word. The first defined SapphireOne Write Pro image border line (in this order: top, right, bottom, left) will be used for all of an image’s borders.
    Border radius (rounded borders) Not supported by Microsoft Word
    Border width Microsoft Word maximum is 12pt, borders exceeding this size will be reduced. Microsoft Word maximum is 12pt, borders exceeding this size will be reduced.   

    Expressions  
    Setting Paragraphs Sections Images
    Expressions Only simple SapphireOne expressions such as “Current date” or “Current time”, or SapphireOne Write Pro reserved local variables ($wp_title, $wp_pageNumber, etc.) are converted to Microsoft Word fields. Other SapphireOne expressions are computed and converted to text or images during the export process. 

    Lists  
    Setting Paragraphs Sections Images
    Indent Converted to 0 for list items (list item indent is converted to hanging indent in Microsoft Word)
    Ordered list type Greek, Armenian, and Georgian are converted to decimal and Hiragana is converted to Katakana in Microsoft Word.

    Pictures  
    Setting Paragraphs Sections Images
    SVG Not supported by Microsoft Word (images in SVG format will be converted to PNG format)

    Size  
    Setting Paragraphs Sections Images
    Minimum height Not supported by Microsoft Word (height is handled automatically)
    Width / Minimum width Not supported by Microsoft Word (paragraph width is handled automatically)

    Spacing  
    Setting Paragraphs Sections Images
    Padding Microsoft Word maximum is 31pt, padding exceeding this size will be reduced. Microsoft Word maximum is 31pt, padding exceeding this size will be reduced.

    Tabs  
    Setting Paragraphs Sections Images
    Default tab stop Not supported by Microsoft Word (will be converted to absolute tab stops)
    Tab leading characters Microsoft Word supports “dot” (….), “dash” (—-), and “underscore” (____) leading characters, all others will be converted to “none”.

    Text  
    Setting Paragraphs Sections Images
    Linethrough Line color different from text color is not supported by Microsoft Word; only solid and double styles are supported
    Style Sheets Paragraph style sheets are converted to paragraph styles.
    Text align Microsoft Word compresses spaces, so justified text layout may be reconfigured. Microsoft Word compresses spaces, so justified text layout may be reconfigured.
    Text shadow SapphireOne Write Pro shadow will be converted to blur and offset, using the default color in Microsoft Word.
    Underline Semi-transparent underlines will be converted to solid. 

    Exporting to HTML and MIME HTML formats

    SapphireOne Write Pro documents can be exported to the HTML and MIME HTML formats using the WP EXPORT DOCUMENT and WP EXPORT VARIABLE commands. Use these tables to check which SapphireOne Write Pro attributes and features are exported to HTML and MIME HTML. The attributes/features are sorted alphabetically. For a detailed list of attributes, see SapphireOne Write Pro Attributes.

    Common Attributes  

    Attribute/Feature Exported Comment
    Background clip  yes 
    Background color (for element, not character) yes 
    Background image  yes 
    Background repeat  yes 
    Background origin  yes 
    Background position  yes 
    Background width and height  yes 
    Border color  yes 
    Border radius  yes 
    Border style  yes 
    Border width  yes 
    Element id  yes 
    Margin  yes 
    Padding  yes 
    Protected  no 
    Style sheet  yes 

    Characters  

    Attribute/Feature Exported Comment
    Background color yes
    Font and font styles yes
    Font size yes
    Strikethrough color no
    Strikethrough styles partially Only solid is exported
    Superscript, subscript yes
    Text color yes
    Text shadow yes
    Text transform partially Small uppercase is not exported
    Underline color no
    Underline styles partially Only solid is exported

    Columns  

    Attribute/Feature Exported Comment
    Column count  no 
    Column rule color  no 
    Column rule style  no 
    Column rule width  no 
    Column spacing  no 

    Document  

    Attribute/Feature Exported Comment
    Break paragraphs in formulas  no 
    Document (meta) information  partially  Only title and subject are exported
    Dpi  no 
    Font default  no 
    Header and footer autofit  no 
    Page margin  no 
    Page orientation  no 
    Page width/height  no 
    Protection enabled  no 
    Tab decimal separator  no 
    User unit  no 

    Images  

    Attribute/Feature Exported Comment
    Alternate text  yes 
    Anchor align  partially  Only right, left, top or bottom
    Anchor embedded  yes 
    Anchor offset  yes 
    Anchor origin  partially  Only for the container box (borders of the web page)
    Anchor to a single page  no 
    Anchor to all pages  no 
    Anchor to all sections of a page  no 
    Background image (and related background attributes)  yes 
    Image display mode  partially  If an image has a background image, it is exported as scaled to fit.
    Image URL yes 
    Vertical align  yes 

    Paragraphs  

    Attribute/Feature Exported Comment
    Absolute tab stops no
    Column break after yes Single column only (multiple columns are not supported)
    Direction yes
    Line height yes
    List font no
    List image yes
    List image height no
    List start number yes
    List string format (custom format) no
    List style type partially Hollow-square, diamond, and club are not exported, decimal-greek is the same as lower-greek 
    Min-height yes
    Min-width no
    New line style sheet no
    Page break after yes
    Page break inside yes
    Section break after (continuous or not) no
    Text align yes
    Text indent yes
    Vertical-align yes
    Widow and orphan control no
    Width yes

    Sections and Page Elements  

    Attribute/Feature Exported Comment
    First page sub-section  no 
    Headers and footers  no 
    Left and right page sub-sections  no 
    Main sections  no  Only document-level attributes are exported to the html body 
    Page margin  no 
    Page orientation  no 

    Tables  

    Attribute/Feature Exported Comment
    Background image (and related attributes)  yes 
    Column break after  yes  Single column only (multiple columns are not supported)
    Horizontal alignment  yes 
    Page break after  yes 
    Page break inside  yes 
    Section break after  no 

    Table Cells  

    Attribute/Feature Exported Comment
    Background image (and related attributes)  yes 
    Height  yes 
    Vertical align  yes 
    Width  yes 

    Table Rows  

    Attribute/Feature Exported Comment
    Background image (and related attributes)  yes 
    Column break after  yes  Single column only (multiple columns are not supported)
    Height  yes 
    Page break after  yes 

    Other Features  

    Attribute/Feature Exported Comment
    SapphireOne formulas  no  Computed and freezed for export
    SapphireOne method links  no 
    Bookmarks and bookmark links  yes 
    URL links  yes 

    Exporting to SVG Format 

    You can export SapphireOne Write Pro document pages to SVG format using the WP EXPORT DOCUMENT and WP EXPORT VARIABLE commands. This page contains additional information and notes on SVG export. 

    SVG Rendering  

    SVG images are rendered according to page settings displayed in Page view mode. The following properties are taken into account:

    • Background attributes (if exported)
    • Borders
    • Margins
    • Orientation
    • Padding
    • Page size
    • Sections (SVG rendering takes into account the section attributes, but the sections themselves are not exported)

    Parts of the document that are exported to SVG:

    • Body
    • Inline images
    • Title (metadata wk title) 

    Parts of the document that are exported to SVG depending on the option parameter:

    • Headers
    • Footers
    • References or values (regarding values, the wk recompute formulas option determines if the formulas are evaluated before export)
    • Background colors 
    • Images defined as background images and anchored images

    The following elements are not exported to SVG:

    • Fonts (converted to CSS styles, but not embedded in the exported SVG. See Font management
    • Links to bookmarks (rendered but not active)
    • Links to URLs (rendered but not active)
    • Customized formula highlighting
    • Metadata
      • Author
      • Subject
      • Creation date
      • Modification date

    Font Management  

    Fonts are not embedded in the exported SVG, so text will be rendered correctly only if the font family and style are supported on the platform where the SVG image is rendered. 

    If you want to make sure that the rendering will be equivalent on all platforms, even when fonts are not available, you can use the wk import google fonts option when exporting a SapphireOne Write Pro document.

    Imported Google fonts override native fonts when the SVG is rendered. If you intend to render the SVG image on the same platform, we recommend not using the wk import google fonts option as rendering with native fonts is always better.

    Note: Only bold and italic styles are preserved. 100% compatibility between native font styles and font style definition in CSS (and thus SVG) is not guaranteed. Export to PDF is more suited for distribution to all platforms or for better WYSIWYG support for fonts, as fonts are embedded in PDF.

    Example  

    This example exports a document page to SVG format and creates an image preview using SVG EXPORT TO PICTURE. var $preview : Picture
     var $options : Object
     var $svgRoot : Text
     var $options : Object
     
     $options:=New object
     $options[wk max picture DPI]:=96
     WP EXPORT VARIABLE(wpDoc;$text;wk svg;$options)
     $svgRoot:=DOM Parse XML variable($text;False)
     SVG EXPORT TO PICTURE($svgRoot;$preview;Own XML data source)

    SapphireOne Write Pro Language

    A complete guide to the Write Pro Language is available here.

    https://doc.4d.com/4Dv19R3/4D/19-R3/4D-Write-Pro-Language.201-5606487.en.html

    Watch how to enter a Stock Adjustment Journal in SapphireOne


    You can review our Blog and YouTube channel for additional information and resources on SapphireOne ERP, CRM and Business Accounting software.

    Was this helpful?

    Next Article

    Transfer Journal