Object specs describe the data that will go into JXCirrus Diary entries. This includes things like:
If JXCirrusDiary was a normal relational database, then an Object Spec would describe a table.
Quick summary of all of the keywords.
Section | Option | Details | Example |
Variables | $<Var> = prompt(); |
Always prompt the user to enter that value. | $<FirstName> = prompt(); |
$<Var> = init("Value"); |
Set Var to "Value" but allow the user to change it
Can refer to other variables. |
$<Year> = init("2013");
|
|
$<Var> = eval("Value"); |
Set Var to "Value" always and don't allow the user to
change it
Can refer to other variables. |
$<Transport> = eval("Bike");
|
|
$<Var> = eval("$=(EXPRESSION)"); |
"$=(...)" refers to an expression that gets evalulated
each time.
Can refer to other variables. Expression syntax is that used by JavaScript. |
$<Area> =
eval("$=($<Width>*$<Height>)");
|
|
$<Var> = auto("00"); |
Each time a child spec references the value, we increment
the counter by 1.
The "00" number of digits refers to the number of digits. |
$<Count> = auto("1");
|
|
System Variables | $<EntryType> |
Defines the type of entry this is:
|
$<EntryType> = eval("Journal"); |
$<Title> |
The overall title of the entry. | $<Title> = eval("$<Firstname>
$<Lastname>"); |
|
$<Details>
|
The details supplied for the
entry. This is a read only value. |
$<SomethingElse> =
eval("$<Details>"); |
|
$<Children> |
The number of children of this
task. This is a read only value. |
$<Title> = eval("Has
$<Children> children."); |
|
$<Start_Time> |
The start date/time for an appointment or journal entry. | $<Start_Time> = init("Sunday 3:00PM"); |
|
$<End_Time> |
The end date/time for an appointment or journal entry. | $<End_Time> = init("Sunday 5:00PM"); |
|
$<Start_After> |
The date/time to start a working on a task. | $<Start_After> = eval("$<ProjectFinish>
+-1 Week"); |
|
$<Due_Date> |
The date/time a task is due. | $<Due_Date> = eval("$<ProjectFinish>"); |
|
$<Duration> |
The duration of a task. | $<Duration> = init("1:00"); |
|
$<TotalDuration> |
The duration of a task (including repeating
tasks). Read only. |
$<Total> =
init("$<TotalDuration>"); |
|
$<Remaining> |
The remaining hours of the task. |
$<MyRemaining> =
eval("$<Remaining>"); |
|
$<TotalRemaining> |
The remaining time of a task (including repeating tasks). Read only. | $<MyRemaining> =
eval("$<TotalRemaining>"); |
|
$<Complete> |
The percentage complete for a task (0-100). | $<Complete> = init("100"); |
|
$<IsComplete> |
Is this task complete (0 = not complete, 1 =
complete). Read only. |
$<MyComplete> =
eval("$<IsComplete>"); |
|
$<IsActive> |
Is this task able to start (i.e. not
complete, and not blocked). 1 = Able to start, 0 =
Blocked or complete. Read only. |
$<MyActive> =
eval("$<IsActive>"); |
|
$<AutoProgress> |
Should percentage complete be automatically updated.
0 - Manual Progress - Record for yourself.. 1 - Based on time spent. 2 - Progress based on the due date. |
$<AutoProgress> = eval("1"); |
|
$<Priority> |
The priority of the task (0-100). | $<Priority> = init("40"); |
|
$<Resource> |
The name of the resource who will do work on the task. |
$<Resource> = eval("$<Manager>"); |
|
$<TimeType> |
The time type to use for allocating time. | $<TimeType> = eval("Work"); |
|
$<Command> |
The commands to execute with the task. | $<Command> = eval("@AUTOCOMPLETE; firefox.exe
$<WebSite>");
|
|
$<Repeating> |
Is this a repeating task/appointment (0 = no, 1 = yes). | $<Repeating> = init("1"); |
|
$<Repeat_Start> |
The start time for each repeating task/appointment. | $<Repeat_Start> = init("Next Mon 4:00AM"); |
|
$<Repeat_Due> |
The finish time for each repeating task/appointment. | $<Repeat_End> = init("Next Fri 10:00PM"); |
|
$<Begin_Repeating> |
The date to start repeating after. | $<Begin_Repeating> = init("1-Jan 4:00AM"); |
|
$<Finish_Repeating> |
The date to finish repeating before. | $<Finish_Repeating> = init("31-Dec 10:00PM"); |
|
$<Exclude_Repeating> |
A set of dates to exclude from the repeating tasks. | $<Exclude_Repeating> =
init("$<MyBirthday"); |
|
$<Depend_Title> |
The name of a task that this depends. | $<Depend_Title> = init("Wash Car"); |
|
$<Prevent_Other_Depend> |
Prevent other tasks from depending on this. | $<Prevent_Other_Depend> = init("1"); |
|
$<Prevent_Depend> |
Prevent this task from depending on others. | $<Prevent_Depend> = init("1"); |
|
$<Bookmark> | Is this task a bookmark entry. |
$<Bookmark> = init("1"); |
|
$<Preserve> |
Prevent this entry from being compacted. |
$<Preserve> = eval("1"); |
|
$<Baseline_Duration> |
The baseline time for this task. | $<Baseline_Duration> = init("1:00"); |
|
$<Baseline_Start> |
The baseline start date. | $<Baseline_Start> =
init("$<ProjectStart>"); |
|
$<Baseline_End> |
The baseline end date. | $<Baseline_End> = init("$<ProjectEnd>"); |
|
$<Baseline_Progress> |
Track evenly between start and end date. | $<Baseline_Progress> = init("1"); |
|
$<Auto_Baseline> |
Create a baseline automatically when the task is created:
Hours - Record the task duration. HoursDate - Record the task duration and start and end date. FollowHours - Adjust the hours as the duration is changed. FollowHoursDate - Adjust the hours and the start/end as the due date is moved. |
$<Auto_Baseline> = init("Hours"); |
|
$<ID> |
The ID number of the entry. Read
only. |
||
$<Spec> |
The object spec name of the
entry. Read only. |
||
Variable Modifiers | private $<Var>; |
Don't display this variable in the entry for or the entry display. | private $<FullName>; |
constrain $<Var> BOOL; |
Constrain this value to be boolean (0,1) | constrain $<CelebrateBirthday> BOOL; |
|
constrain $<Var> INT "FORMAT"; |
Constrain this value to be an integer.
Format is C-style printf specifier. |
constrain $<BirthYear> INT "%04f";
|
|
constrain $<Var> FLOAT "FORMAT"; |
Constrain this value to be a floating point number.
Format is C-style printf specifier. |
constrain $<Salary> FLOAT "%.2f";
|
|
constrain $<Var> DATE; |
Constrain this value to be a date/time. | constrain $<ProjectFinish> DATE; |
|
constrain $<Var> DURATION; |
Constrain this value to be a duration. |
constrain $<ProjectDuration>
DURATION; |
|
constrain $<Var> LOCATION. |
Constrain this value to be a
latitude/longitude location. |
constrain $<LatLon> LOCATION; |
|
constrain $<Var> CHOICE "OPT1,OPT2"; |
Constrain this value to be one of a set of choices.
Options are comma separated. |
constrain $<Transport> CHOICE
"Plane,Train,Automobile"; |
|
constrain $<Var> REFERENCE "${Spec}
$<Var>"; |
Constrain this value to be chosen from another variable.
You specify the other spec and variable name for the value. Spec = SYSTEM and Var = PEOPLE is a special case that allows you to select from either resources or the Title value for any Person entries. Spec = SYSTEM and Var = RESOURCES is a special case that allows you to select from resources. |
constrain $<BestFriend> REFERENCE "${Person}
$<FullName>");
|
|
Children | $[Child] = ${Spec}; |
A single mandatory child. | $[BDay] = ${Birthday}; |
$[Child] = ${Spec}[]; |
Zero or more of a child. | $[Celebrations] = ${Anniversary}[]; |
|
$[Child] = ${Spec}[+]; |
One or more of a child. | $[Update] = ${NewsUpdate}[+]; |
|
$[Child] = ${Spec}[^]; |
Zero or more of a child, but create a single one when the object is first created. | $[Update] = ${NewsUpdate}[^]; |
|
$[Child] = ${Spec}[-]; |
Retain existing children, but don't allow new children of that type. | $[Graduation] = ${Event}[-]; |
|
$[Child] = ${Spec=Derived}; |
When the child could be one of several specs, default to a specific derived spec. | $[Anniversary] = ${Anniversary=Birthday}; |
|
Specs | inherits SPEC; |
Derive this spec off another base SPEC. | inherits Task; |
baseonly; |
Use this as the base for other specs, but don't allow this to be created explicitly. | baseonly; |
|
defunct; |
Do not allow new entries with this spec type, but don't complain about existing ones. | defunct; |
|
Scripts | @Script MyScript @Shortcut C
|
Define a JavaScript script.
MyScript is the name of the script. Shortcut (optional) defines a key that can be pressed after Shift-M. |
@Script Finish @Shortcut C
|
Trigger Scripts | on_start |
Called when a task is started. | @Script on_start
|
on_stop |
Called when a task is stopped. | @Script on_start
|
|
on_complete |
Called when a task is completed. | @Script on_complete
|
|
on_create |
Called when a task is created. | @Script on_create
|
|
on_edit |
Called when a task is edited. | @Script on_edit
|
|
on_recalculate |
Caleld when View-Recalculate is selected (not during normal recalculate). | @Script on_recalculate
|
Variables define what information is stored in the entry. Variables are either:
Variables are defined in the spec as:
$<MyVariable>
Variables need to be declared in the spec before they can be used elsewhere. This can come in several forms.
$<MyVariable>
= prompt();
This tells the system that when a new entry of this type is created, the user should be prompted to fill in this value (in fact, they have to fill in the value, or the system will give them a warning). They can opt to leave it blank, but they still must put the cursor in the field at least once to initialise the value.
$<MyVariable>
= init("Hello");
This works a little bit like "promptUser" except that:
You would use this form if you want to set a default value, but let the user change it if they want to.
$<MyVariable>
= eval("12.5");
Eval means ALWAYS set this variable to this value. The user cannot change it. In the case above, MyVariable will be set to 12.5 no matter what.
This might seem a little bit curious at first, but there is a point, so listen up... There are 2 ways that "eval" is useful:
This is how you can set one variable to be based on another one.
$<First_Name> =
promptUser();
$<Last_Name> =
promptUser();
$<Full_Name> =
eval("$<First_Name> $<Last_Name>");
So the system will get the user to fill in a first name (lets say Joe) and a last name (lets say Bloggs). Full_Name will now be "Joe Bloggs". The user cannot change Full_Name, but if they change First_Name to Susan, Full_Name will automatically change to "Susan Bloggs".
$<MyVariable>
= auto("00");
This is a special type of variable which can be used to create a unique counter for other entries. For example, if we wanted to have a testing spec, with a whole lot of test rounds under it..
Testing Spec
$[Round] =
${TestRound}[+]
;
$<TestRound>= auto("0");
Test Round Spec
$<Round> =
init("$<^TestRound>");
Each time we create a new Round under Testing, the TestRound value goes up by one.
NOTE: Don't use eval("$<^TestRound>");
- Eval
gets run each time round, so it would keep on incrementing the
counter. Init is the only type that will trigger it to increment.
NOTE: You can start at any number $<TestRound> =
auto("5");
will go 5, 6, 7, 8...
NOTE: The number of digits you set in the auto definition defines
leading zeroes, for example $<TestRound> =
auto("000");
will go 000, 001, 002...
Lets imagine we want to make one value equal some mathematical combination of other values. Here is an example of a couple of slightly handy calcs:
$<Width> =
init("5");
$<Height> =
init("20");
$<Perimeter> =
eval("$=($<Width>*2+$<Height>*2)");
$<Area> =
eval("$=($<Width>*$<Height>)");
The "$=(...)" section means "evaluate this expression". The expressions work a bit like the formulas in a spredsheet, except that they reference other variables rather than other cells.
Here are some examples of expressions:
$=($<X>*$<X>)
Gives X squared.
$=(($<X>+5)*$<Y>)
(X+5)*Y
$=($<MyValue>/2)
Halve it.
$=($<MyValue>-1)
Take away 1.
It is possible to put "if" type clauses into the expressions.
$=($<MyValue>>5?5:$<MyValue>)
Means that if MyValue > 5 then the expression will return 5, otherwise return MyValue.
Conditional clauses like this have the form CONDITION ? TRUE_ANSWER : FALSE_ANSWER
If CONDITION is true, then the result is TRUE_ANSWER, otherwise it is FALSE_ANSWER.
If there is a mistake in the expression, then the result will just be the expression itself - So if you see an expression that just lists itself as the result, then you probably have a mistake in it.
For the techies amongst us - The expressions we are using here probably look slightly familiar, and you are probably right. The expressions in JXCirrusDiary are actually the same as expressions in JavaScript. So, if you are feeling brave, you could embed a whole JavaScript function into this expression and evaluate it. One thing to note though - Just because you can, doesn't always mean you should (hint try macros and functions instead).
This is a list of the system-defined variables:
$<Title>
This is the actual title of the entry. It is the value that is shown in the diary tree, the day view etc.
An example... $<Title> = eval("Task:
$<Summary>")
; - If $<Summary> was "Weeding",
the title would be "Task: Weeding".
$<Details>
These are the details supplied by the user. You
cannot change this value (only copy it to other variables).
$<Children>
The number of children of the task (in the tree). You
cannot change this value (only use it in other variables).
$<EntryType>
This is the type of entry. The choices are:
An example would be $<EntryType> = eval("Person");
$<Start_Time>
This applies to Appointments and Journal entries. For appointments, this is the start time of the appointment. For journal entries, this is the start of the journal time.
An example could be $<Start_Time> = init("2:00PM");
$<End_Time>
This applies to Appointments and Journal entries. For appointments, this is the end time of the appointment. For journal entries, this is the end of the journal time.
An example could be $<End_Time> = init("Tue
5:00PM");
$<Start_After>
This applies to Tasks. If this is set, work should not start on the task before this time.
An example could be $<Start_After> = init("Thu
4AM");
which would mean don't start work on this task
until after 4AM on Thursday.
$<Due_Date>
This applies to Tasks. This is the time that the task is due by.
An example could be $<Due_Date> = init("Sat 6PM");
which would mean that the task must be finished before 6PM on
Saturday.
$<Duration>
This applies to Tasks. This is the amount of time that the task is expected to take.
An example could be $<Duration> = init("1:30");
which means it should task one and a half hours.
$<Complete>
This applies to Tasks. It is the percentage complete for the task.
0% - Means that the task has not been started.
100% - Means that the task is complete.
An example could be $<Complete> = init("100");
would mean that the task would start off marked as complete.
$<AutoProgress>
This applies to Tasks and Appointments, and lets you specify whether the progress (ie % Complete) is set by the user or set automatically. There are 3 options for this:
0 - Manual Progress - You record how far you are through the task yourself.
1 - Progress based on time spent - i.e. if this is a 2 hour task, and you spend 1 hour, then it will automatically set the progress to 50%.
2 - Progress based on the due date - ie if this task starts on Monday and ends on Friday, then on Wednesday it the progress will automatically be set to 50%.
An example... $<AutoProgress> = eval("1");
$<Priority>
This applies to Tasks. It is the relative priority of the task (i.e. which task should be done first). The range is 0 to 100, with 0 being unimportant, and 100 being most important.
An example... $<Priority> = init("40");
$<Resource>
This applies to Tasks and Appointments. The resource name should match a name you have entered in the resources dialog.
For tasks, this is the name of the person who will be working on the task.
For appointments, this is the name of the person attending the appointment.
An example... $<Resource> = init("Bill Example");
$<TimeType>
The name of the time type you want this type of object to use. This is usually applicable to tasks. See Time Types.
An example... $<TimeType> = init("Work");
$<Command>
This is a command that will be executed as part of this task. For more information on commands, see Commands.
The key thing about commands is that when you specify a variable value, you cannot use newlines, so commands are defined slightly differently to commands in the Diary Entry dialog. A newline is replaced by a semicolon ";" in the command value.
For example, if you wanted to specify something like:
@DIR=$<WorkDir>
@AUTOSTART
make clean
the command would be
$<Command> =
eval("@DIR=$<WorkDir>; @AUTOSTART; make clean");
$<Repeating>
This applies to tasks and appointments. It indicating whether that task or appointment is repeating. It can only have values of "1" (repeating) and "0" (not repeating). See Repeating Tasks.
An example... $<Repeating> = init("1");
$<Repeat_Start>
This applies to tasks and appointments. It indicates the next start after time for a repeating task. See Repeating Tasks.
An example... $<Repeat_Start> = eval("Tue 12:00pm +1
Week");
$<Repeat_Due>
This applies to tasks and appointments. It indicates the next due date for a repeating task. See Repeating Tasks.
An example... $<Repeat_Due> = eval("Fri 6:00PM +1
Week");
$<Begin_Repeating>
This applies to tasks and appointments. It indicates the date after which the task should start repeating. If left blank, it will begin repeating immediately. See Repeating Tasks.
An example... $<Begin_Repeating> =
eval("$<Project_Start>");
$<Finish_Repeating>
This applies to tasks and appointments. It indicates the date after which the task should stop repeating. If left blank, it will repeat forever. See Repeating Tasks.
An example... $<Finish_Repeating> =
eval("$<Project_End>");
$<Exclude_Repeating>
Lets you exclude specific dates to date ranges from the repeating. See Repeating Tasks.
An example... $<Exclude_Repeting> =
eval("$<MyBirthday>");
$<Depend_Title>
This applies to tasks and appointments. This allows you to have this task depend on another task with a specific title. See Dependencies.
An example... $<Depend_Title> = eval("Kickoff
Meeting");
This would have this task depend on the closest task with the title "Kickoff Meeting".
$<Prevent_Other_Depend>
This applies to tasks and appointments. This allows you to nominate other task from depending on this one. You would use this if you have set up some automatic dependencies, but for some reason this task should no longer block other tasks (such as if it is finished enough for the dependencies to keep going). Its valid values are "1" (to prevent others depending on this) or "0" to allow others to depend on this. See Dependencies.
An example... $<Prevent_Other_Depend> = init("1");
$<Prevent_Depend>
This applies to tasks and appointments. This allows you to specify that this tasks should be blocked by other tasks that it depends on. This is useful if your dependendcies have been set up automatically, but you know that you can actually proceed with this work. Its valid values are "1" (which stops this being blocked by dependent tasks) or "0" to keep all dependencies active. See Dependencies.
An example... $<Prevent_Depend> = init("1");
$<Baseline_Duration>
This applies to tasks. When you save a baseline for a task, the baseline is the time that you originally expected the task to take. It allows the system to warn you if a task has already taken longer than expected, or looks like it will blow out. See Baselines.
An example... $<Baseline_Duration> = eval("10:00");
$<Baseline_Start>
This applies to tasks. When you save a baseline time for a task, then that time is the time that you expected a task to start (for example, in a project plan). It lets the system warn you if the task is starting later than expected. See Baselines.
An example... $<Baseline_Start> =
eval("$<Project_Start>");
This means that you would expect the task to start immediately when the project starts.
$<Baseline_End>
This applies to tasks. When you save a baseline time for a task, then that time is the time that you expected a task to finish (for example, in a project plan). It lets the system warn you if the task is likely to finish later than expected. See Baselines.
An example... $<Baseline_End> =
eval("$<Project_End>");
This means that you would expect the task to be finished when the project finishes.
$<Baseline_Progress>
This applies to tasks. This lets you tell the system that you expect this task to be spread evenly between the $<Baseline_Start> value and $<Baseline_End> value. An example of how you might use this is if you had a project management task and you wanted to make sure you weren't burning too much of that time at the start of the project. If the Baseline Start and Baseline End were the start and finish of the project, it would warn you if you were spending the project management budget too fast. The valid values for this are "1" if you want to track baseline progress, and "0" if you do not want to track it. See Baselines.
An example... $<Baseline_Progress> = eval("1");
$<Auto_Baseline>
This applies to tasks. See Baselines. This value gets tasks to automatically save a baseline value when the task is first created. This works exactly as if:
You might use this for some sort of standard project task where you want to make sure there is some kind of overall baseline recorded.
The values for it can be:
$<Auto_Baseline> = eval("Hours");
Just saves the hours.
$<Auto_Baseline> = eval("HoursDate");
Saves the hours and the date.
$<Auto_Baseline> = eval("FollowHours);
Will update the baseline hours when the task hours change.
$<Auto_Baseline> = eval("FollowHoursDate");
Will update the baseline hours and the start and end date when the task hours change.
$<Auto_Baseline> = eval("");
Stops it from saving automatic baselines (but you can still save it manually). Yes, this is the same as not defining $<Auto_Baseline> at all so why do it... If you inherit off another object spec that sets $<Auto_Baseline>, then you will get that value, so this is a way of stopping that from happening.
NOTE: One tricky thing about this value; When it saves auto-baselines, you can't clear the baseline for the task. If you do clear the baseline, then, like some kind of irritating pedant, it will go and save it again.
If you want to use a variable in your spec, but you don't want to clutter up the form with extra values, you can use the "private" keyword.
private
$<FullName>;
This makes the variable "FullName" usable in the spec, but not visible on the form (and hence not editiable by the user). This could be used in the situation like this:
$<FirstName> =
promptField();
$<Surname> =
promptField();
$<FullName> =
eval("$<FirstName> $<Surname>");
private
$<FullName>;
$<Title> =
eval("Person: $<FullName>");
This lets you use FullName in the title without showing it on the form.
If you want to make many variables private, just separate them by commas:
private
$<FullName>, $<Age>;
You might want some variables to only contain certain types of values. For example $<Quantity> might alsways need to be a number, and $<CompleteDate> might always need to be a date.
constrain
$<Variable> TYPE [PARAMETERS];
For example:
constrain
$<ProjectFinish> DATE;
This makes sure that $<ProjectFinish> will be interpreted as a date.
The main effect of the constraint is in the edit dialog - If a field has a constraint, the user interface will change to match that constraint. For example: BOOL will be a tick-box rather than a field. DATE will expand the value to the full date (i.e. "Tue 4PM" might expand to "Tue 26-Feb-2013 16:00:00").
The different constraint types are:
Constraint | Meaning | Parameters | User Interface | Example |
INT | The field will only handle whole numbers (ie 1, 2, 3). | Format (C-style format string for ints, i.e. "%02d" means 1 will be displayed as "01") - Optional. | The field will change the field to a whole number. | Constrain $<Count> INT "%3d";
Constrain $<Age> INT; |
FLOAT | The field can contain any number (i.e. 1.5, 22.66, 12). | Format (C-style format string for floats, i.e. "%0.1f" means 3 will be displayed as "3.0") - Optional. | Constrain $<Cost> FLOAT "%.2f";
Constrain $<Average> FLOAT; |
|
BOOL | The field can contain a yes or no/true or false value. | None | The form will show a checkbox. | Constrain $<Active> BOOL; |
DATE | The field can contain a date/time. | None | The field will change to a fully expanded date after editing. | Constrain $<Finish> DATE |
CHOICE | The field can contain one of a set of choices. | "Value1, Value2..." (comma separated list of choices) | The field will contain a dropdown box with the choices. | Constrain $<Transport> CHOICE "Train, Plane, Automobile"; |
REFERENCE | The field can contain one of a set of choices, which are the unique values from another variable within the database. | "${SPEC} $<Variable>" gives the spec name and the variable the value comes from. | The field will contain a dropdown box with the values from the other variable. | Constrain $<Name> REFERENCE "${Person} $<FullName>"; |
An example of how the reference
constraint might be
used:
If you have an addressbook containing a number of Person specs... These specs might have a variable called $<FullName> which is that person's full name. If you wanted to have an appointment class that let you select the name of a person in your addressbook (the variable here is $<AppointmentPerson>, you could use:
constrain
$<AppointmentPerson> REFERENCE "${Person}
$<FullName>";
NOTE: The Constrain keyword ONLY applies when values are edited - It does not change existing values in the background. So if you make a change to a spec to add a constraint, the constraint will not be applied until you edit the entry that contains that value. The reason for this is that you could do some dramatically bad things to the data in a field, and forcing an edit will give the user a chance to review the changes to the data before they are put in force.
There are some special cases, where the REFERENCE can refer to values used by the system itself. If the spec is set as SYSTEM, you can use the following variable names:
For example:
If you wanted the reporter of an issue to be any resource in the system, or anyone in any addressbook, you could use this.
constrain
$<Reporter> REFERENCE "${SYSTEM} $<PEOPLE>";
If you wanted the developer of an issue to be set to any available resource, you could use this:
constrain
$<Devloper> REFERENCE "${SYSTEM} $<RESOURCES>";
When you use variables in an object spec, the system will look for the variable name in this spec first. But if it doesn't find it, it will use the value from the parent spec (and onwards and upwards to the top of the tree view).
For example:
This spec defines a project.
$<Project>
= prompt();
$[Phase] = ${Phase}[];
$<Title>
= eval("$<Project>");
This spec defines a phase in a project. This will be a child of the project.
$<Phase> = prompt();
$<Title> =
eval("$<Project>: $<Phase>");
In the phase spec, the $<Project> value in the title of the phase, will come from the Project spec, one level up. The system looked for the $<Project> variable in the phase spec, but couldn't find it, so looked further up the tree.
Lets imagine that we have a Task spec that can have SubTask children. And the SubTasks can be split into further SubTasks.
The Task spec.
$<Task> = prompt();
$<Title> =
eval("$<Task>");
$[SubTask] = ${SubTask}[];
The SubTask spec.
$<Task> = prompt();
$<Title> =
eval("$<Task>");
$[SubTask] = ${SubTask};
(yes, at the moment, the task and subtask are identical, but we are going somewhere with this).
Lets imagine that we have a task called "5 Straight Street". A sub-task is "Fix Garden" and a sub-task of that is "Path Paving". One problem is that the title of the bottom level task is just "Path Paving", but we don't know what this applies to... We can see it fine if we are in the tree view, but if we are looking at the dat view, we have no idea what the "Path Paving" is part of. So, imagine we want the task title to be "5 Straight St - Fix Garden - Path Paving"...
Here is how we might do it in the SubTask spec
$<Title> =
eval("$<^Title> - $<Task>");
Note the "^" symbol before the second Title... That means grab the Title variable from the parent, and ignore the value in the current entry.
defunct;
Use this if you want to stop using this spec, but want to keep a few old ones of this type kicking around in the database. This just means "Don't let any users create one of these". It won't appear in the list of options for creating a new child.
$[TheirBirthday] =
${Birthday};
This will create a single Birthday object as a child. You cannot add more birthday objects at a later date.
$[Anniversaries] =
${Anniversary}[];
Allows as many Anniversary objects as you like. This will not actually create an anniversary child until you add one using "Create Child" - Anniversaries will be shown as one of the options.
$[People] = ${Person}[+];
Allows as many Person objects, but will start with a minimum of 1. You can create more using "Create Child".
$[People] = ${Person}[^];
This one is the same as "[]" except that when the object is first
created, it will add a "Person" child by default. You are free to
delete that person straight away if you like. The main use for
this beast is when you are adding onto a spec and want all of the
new instances to have one of these, but not the old ones. For
example, if you are tracking some kind of project, you might want
to add a step to review everything at the end (called Review)...
If you added this using "$[Review] = ${Review}[+];
",
then all of your finished projects would get a Review object added
to them (which you would have to close off). If you added "$[Review]
= ${Review}[^];
", then it will only be added to new ones,
but not the old ones.
$[TheirGraduation] =
${Anniversary}[-];
Use this is if you don't want to create any Graduations as a child of this spec anymore. Lets say you used to use "TheirGraduation" as a single child entry, but now it is a nuisance and not relevant. If you just delete the child "TheirGraduation", then JXCirrusDiary will complain at you that their are invalid children (if there are a few TheirGraduation children still kicking around). You could just use cut/paste-as to move them somewhere else, but that may be loads of them. The "[-]" after the child name means - If it already exists, then thats OK, leave it there. But DON'T make any new ones.
There are times when you may have child type that has several different inherited types (see Inherit). For this example, assume we have an Birthday type with inherited BirthdaySkype (because they are overseas) and BirthdayParty (because we care and they are here). Lets say we want automatically create a Birthday type, but because most birthdays have a party, we want it to default to BirthdayParty, but still let us switch over to BirthdaySkype. We would put:
$[Birthday] =
${Birthday=BirthdayParty};
The "=BirthdayParty" means use the inherited BirthdayParty spec as the usual one.
One of the powerful features of Object Specs is the ability to inherit the details from one object spec into another and modify it slightly.
When one spec inherits another one, it gets the same variables, children and scripts as the spec that it inherits, but can provide extra information. This works the same as inheritance in programming languages such as Java and C++.
Here is an example:
We have a spec for contacting a person. Lets call it Contact
$<Method>
= prompt();
$<Person>
= prompt();
$<Repeating>
= init("1");
$<Frequency>
= init("1 week");
$<Evening>
= init("Wed");
$<Repeat_Start>
= eval("$<Evening> 6:00PM +$<Frequency>");
$<Title> =
eval("$<Method> $<Person>");
$<Repeat_Due>
= eval("$<Evening> 9:00PM +$<Frequency>");
If Method is "Call", person is "Jill", evening is "Tue", then the title will be "Call Jill", and it will repeat each week on Tuesday evening between 6 and 9PM.
Ok, imagine you are very organised, and you do all phone calls on Thursday night, and all emails on Wednesday. You can specify a Call spec.
inherits
Contact;
$<Method>
= eval("Call");
$<Evening>
= eval("Thursday");
private $<Evening>;
private
$<Method>;
The Call spec includes everything that the contact spec has, but sets the contact method to "Call" and will always repeat on Thursday evening. Since the user doesn't get to edit Method or Evening, we can hide them from view and only use them in the title.
The Email spec might look like this.
inherits
Contact;
$<Method>
= eval("Email");
$<Evening>
= eval("Wednesday");
private $<Evening>;
private
$<Method>;
Lets take this further... Imagine that had a child task specified as this:
$[Contact]
= ${Contact}[];
When you go to create a Contact task, you will be prompted to choose between a "Contact" spec, a "Call" spec and an "Email" spec.
If you didn't want to see the free-form Contact spec (lets imagine that you only ever want to call or email), put in this keyword in the Contact spec.
baseOnly;
This means that this spec will only ever be used for other specs to inherit from, but you will not be able to create a child of that type.
A few notes about inheriting specs:
$<Day>
= eval("Tue");
in the base spec, and $<Day>
= eval("Wed");
in the inherited spec, the Day will be
Wed.$[Job] =
${Task}[]
; - That means that you can have as
many child tasks as you like with the Job tag. If you use $[Job] = ${Task}[-];
in the inherited spec, then that will prevent the inherited spec
from having any child Task objects.One of the nifty labour saving devices available in JXCirrusDiary are scripts. Scripts let you do things like:
Scripts in JXCirrusDiary are a little bit like macros in Excel or Word.
The language that JXCirrusDiary uses for its scripts is JavaScript (which should be nice and familiar to anyone who has done a spot of web development, and nice and easy to learn if you haven't).
To attach a script to an Object Spec, use this sort of format:
@Script MyScript
>"
...
"<;
This will create a script called "MyScript" which will appear in the "Script" menu when you select that entry, and also on the toolbar.
You can add as many scripts as you like to an object spec.
For more information on scripts, see the scripts section of the manual.
Here are 3 related specs
$<EntryType>
= eval("Person");
$<Name>
= prompt();
$<Title>
= eval("$<Name>");
$<Birthdate>
= prompt();
constrain
$<Birthdate> DATE;
$[Anniversary]
= ${Anniversary=Birthday}[];
$<EntryType>
= eval("Task");
$<Anniversary>
=
prompt();
$<Date>
= prompt();
constrain
$<Date> DATE;
$<Title>
= eval("$<Person> - $<Anniversary>");
$<Due_Date>
= init("$<Date>");
$<Due_Date>
= init("$<Date> +-3 weeks");
$<Repeating>
= init("1");
$<Repeat_Start>
=
eval("$<Date> +-3 Weeks +1 Year");
$<Repeat_Due>
= eval("$<Date> +1 Year");
inherits
Anniversary;
$<Date> =
eval("$<Birthdate>");
$<Anniversary>
=
eval("Birthday");
Here are the salient points: