View source for Documentation:Calendar package

<message>Write the content here to display this box</message>
==== What is it? ====
The Calendar package is a model that implements classes, making aggregation (for statistics, for example) easy.

It follows a common pattern with dimensions from data analysis. By prepopulating the database with days, months, years, weeks, etc., you can easily (and efficiently) find data to present in a diagram or table.

This model is cross-linked between all entities making the "conversion" between different calendar objects easy.

This package also contains views for creating, viewing, and maintaining the model content.[[File:Calender model diagram.png|none|thumb|776x776px|link=https://wiki.mdriven.net/index.php/File:Calender_model_diagram.png]]

==== Download it here ====
[[Special:Redirect/file/CalendarPackage.modlr|CalendarPackage.modlr]]

==== '''Notes on Usage''' ====
# The Calendar "main class" is a Singleton. Use Calendar.SO as a short way to access the singleton object.
#* For example in OCL: <code>Calendar.SO.Today</code> will return a Day object for today.
# Use the methods in Calendar to quickly find the Day for a given date when you link new or existing data to the structure.
# There are also several helper functions to find the next/previous day, week, or month or calculate the time between them.
#* For example in OCL: <code>Day.GetDayForDate()</code> returns a Day object by building a dictionary first for quick lookups.
# Integers called '''Ordinals''' are used to have a stable way to calculate how far apart objects are in time.

==== Starting Up ====
* To create the data structure, start by using an action to create the years you want.
* Then with that, call FixupCalendar to create months and days of the calendar. You can call FixupCalendar many times without losing any data. It will simply update or correct problems.
* Weeks are a bit special. Week definitions vary in different parts of the world. Therefore, the WeekDefinition class sets the first day of the week, and weeks are then generated based on that.
* You can also define Saturday and Sunday (for example) as the "days off" every week.
* Use the country setting to define the default week definition for your users.

==== How To Use the Calendar Package in Your Model ====

* Merge the Calendar package into your model using [[Documentation:TK Live View|TKLiveView]].

* For all the Classes you want to capture the Date and Time details of records that can be used for detail statistical analysis, link the classes to the '''Day''' Class in the Calendar package. The '''Day''' Class is the linking point between your model and the Calendar package.
* Startup the Application and Goto the '''DataStructureBrowser''' ViewModel.
* Create a Year using the ''Create Year'' action.
* Execute the ''Ensure Months and Days'' action to create months and days  for the selected Year.
* Lastly, execute ''Fixup Calendar'' action to fix any issues with the Calendar data.

==== Example: Account Class that will be used for a Detailed Statistical Analysis ====
[[File:calendar-package-example.png|alt=Calendar Package Example|none|thumb|748x748px]]

The Calendar package when setup contains data on the years created, their months and days so the only remaining thing to do is to link your Model Classes to the existing days and these days provide access to their months and year.

* Create a unidirectional relationship between the '''Account''' Class and '''Day''' Class

===== How to set the Day Association Link Data =====

* If the date should be set on the same day when class data is added or created, then use <code>Calendar.SO.Today</code> to set '''Day''' association data link

'''''OnCreate''''' function body on '''Account''' Class<syntaxhighlight>
self.Day:=Calendar.SO.Today
</syntaxhighlight>
[[Category:Packages]]
[[File:2024-10-21 02h04 27.png|none|thumb|740x740px]]

If '''Account''' Class has existing data and dates that you want to link to the '''Day''' Class, use the '''''GetDayForDate''''' Method on '''Day''' Class to set the '''Day''' association data link<syntaxhighlight>
Account.allinstances->foreach(i|
    i.Day:=GetDayForDate(self.CreateTime)
)

</syntaxhighlight>where ''self.CreateTime'' is the date and time attribute on '''Account''' Class.

==== How to Get the Hour of  a Date ====
Create a unidirectional relationship between the '''Account''' Class and '''HourOfDay''' Class in the Calendar Package
Set the association to Derived and Set the ''DerivationOcl'' of ''CalculatedHourOfDay'' <syntaxhighlight>
HourOfDay.GetHourForTime(self.CreateTime)
</syntaxhighlight>where ''self.CreateTime'' is the date and time attribute on Account Class.
[[File:2024-10-21 05h19 25.png|none|thumb|769x769px]]

{{Edited|July|12|2025}}

[[Category:TOC]]