Editing Documentation:The Editor and data format

Let’s see how the information about events is stored on the server. Make sure that the library is open (click ‘Events’ button in the bottom right corner of the screen if needed)

Then open Menu (click ‘Menu’ button in the bottom left corner of the screen). Now select ‘Show Cache and Edit buttons’. 

[[File:ShowCacheAndEditButtons.png]]

You should see that Cache and Edit buttons have appeared in the Library next to each folder and layer of edits.

[[File:CacheAndEventButtons.png]]

Click an Edit button next to some layer, and another Edit button next to some folder. Pages with wikitext should open in separate tabs. Examine the data and compare it to what you see on the timeline. Here is an example for a [https://historytimeline.app/wiki/index.php?title=HistoryTimelineLayer:Kings%20of%20Rome&action=edit layer]. Here is an example for a [https://historytimeline.app/wiki/index.php?title=HistoryTimelineFolder:Ancient%20Rome&action=edit folder].

Let's look at this example:

[[File:RomanKingsDataExample.png]]

To change something on the timeline you edit wikitext on an appropriate page. If you need to add a folder or a layer, you have to create a corresponding page on the wiki.  

Before you edit anything on this wiki, you edit and test things locally on your computer. So, let’s next learn how to use the Editor.

==The Editor==
There should be a button called ‘Editor’ in the bottom left corner of the screen next to the Menu button. If you don’t see it, it’s because the browser window is too small to fit the Editor. On a desktop try making the browser window fullscreen. If you have a small-screen device like a mobile phone, you won’t be able to use the Editor.

Open the Editor. Let's add a couple of events, like so:

[[File:EventsInEditor.png|300px]]

Don't worry about the last line that says something about Category. It will be added automatically. 
Once you click the 'Update layer' button the events should show up on the timeline:

[[File:EventsExample.png|450px]]

As you can see there are two kinds of events: 
:time intervals, represented by horizontal bars; 
:instantaneous events, represented by cards.

===Event format===
There are 7 data fields for each event:

[[File:DataFormat.png]]

Some data fields are used by one kind of event but not the other. Others are used by both.
Let’s go through all of the data fields one by one.

''Visible text'' - for time intervals try to put short titles here, not whole sentences. You can use the ''Comment'' field to put longer text there. 
For instantaneous events the text can be longer, but don’t put entire articles there. One or two sentences should suffice.
You can use some of the features of Wikipedia’s wikitext in the cards. For example, to add a link, use double brackets. 
If you want the link title to be different from the page name, specify it after vertical line.

[[File:LinksInsideTextExample.png]]

Look at the third line. The second link contains visible text (Caesar) that differs from the page title (Julius Caesar). Also note that you can use <code><nowiki>\n</nowiki></code> as a new line character.
This line produces an event on the timeline that looks like this:

[[File:LinksInsideCardExample.png]]

If you want to link to a page outside of Wikipedia, provide a full link that starts with http or https. For example <code><nowiki>[[google.com]]</nowiki></code> will create a link to this page on Wikipedia <code><nowiki>https://en.wikipedia.org/wiki/Google.com</nowiki></code> (whether such page exists or not). To avoid this you should create a link like so: <code><nowiki>[[https://google.com|google.com]]</nowiki></code>

You can make parts of the text ''italic'' by enclosing those parts with double apostrophes: <code><nowiki>''italic text''</nowiki></code>. To make some text '''bold''', enclose it with triple apostrophes: <code><nowiki>'''bold text'''</nowiki></code>.

You can make a time interval invisible by putting the word ''invisible'' in the ''Visible text'' field. This will prevent other time intervals from occupying its space. For an example of when this feature can be useful let’s look at Roman emperors. 

[[File:DynastiesGap.png]]

We want to have a gap between Julio-Claudian and Flavian dynasties but we don’t want emperors to ‘fall’ through this gap. If you just specify dynasties and then emperors like this:
<blockquote><poem>
Julio-Claudian dynasty;;;;01.16.-27;06.08.68;
Flavian dynasty;;;;12.21.69;09.18.96;
Nerva–Antonine dynasty;;;;09.18.96;12.31.192;
Severan dynasty;;;;04.09.193;03.19.235;
Crisis of the Third Century;;;;235;284;

Augustus;;d;;01.16.-27;08.19.14;
Tiberius;;;;09.18.14;03.16.37;
Caligula;;;;03.18.37;01.24.41;
Claudius;;;;01.24.41;10.13.54;
Nero;;;;10.13.54;06.08.68;

Galba;;;;06.08.68;01.15.69;
Otho;;;;01.15.69;04.16.69;
Vitellius;;;;04.18.69;12.20.69;
Vespasian;;;;12.21.69;06.24.79;
</poem></blockquote>

you’d end up with this:

[[File:EmperorsFallThrough.png]]

Just specify an invisible time interval between the dynasties:
<blockquote><poem>
Julio-Claudian dynasty;;;;01.16.-27;06.08.68;
invisible;;;;06.08.68;12.21.69;
Flavian dynasty;;;;12.21.69;09.18.96;
</poem></blockquote>
and you’ll get this:

[[File:InvisibleDynasty.png]]

It maybe helpful to temporarily make the time interval visible by using any text other than ‘invisible’. This way you can see where you put the time interval before making it invisible. For example, if you temporarily use this: <code>visible;;;;06.08.68;12.21.69;</code> you’ll see this:

[[File:VisibleDynasty.png]]

''Link'' - this field is only used for time intervals. By default the visible text of the time interval is the link to the corresponding Wikipedia page. If you want the link to be different from the visible text, specify the actual link in this field. If you want to link to a page outside of Wikipedia, use the full link (which starts with http or https). If you don't want the text to be a link at all, put a hyphen in the ''Link'' field. The text in this case will become grey instead of white and will not be clickable. 

''Comment'' - this field is only used for time intervals. If you put some text in it (for example: <code><nowiki>some time interval;;;this is a comment with a [[Hannibal|link]];1978;1982;</nowiki></code>), the plus button will appear on the time interval:

[[File:TimeIntervalWithCommentExample.png]]

When you click on that button the comment will appear in the middle of the screen. 

[[File:CommentExample.png]]

Inside the text of the comment you can use all the wikitext tricks just like in the ''Visible text'' field.

''Start date'' and ''End date'' - Instantaneous events have only start date, while time intervals have both start and end dates. The date format is this: MM.DD.YYYY. This is an example of an event with a full date <code>some event with a full date;;;;05.25.1965;;</code>. Also, you can specify only month, without a date: <code>05.1965</code>. Or you can specify only year: <code>1965</code>. When you specify only year, the event will point to a moment between June and July of that year. If you specify month without a date, the event will point roughly to the middle of that month, a moment between 15th and 16th day of that month. In general, when event is pointing to a moment between days, that shows that we don't know the date precisely, and the positions of events on the timeline should not be taken literally in such cases.

To specify that a year is BC/BCE use the minus sign. Note, that the minus should go before the year, not entire date. For example: <code>03.15.-44</code> is correct, and <code>-03.15.44</code> is not. Also note that even though we use the minus sign, we don’t use the astronomical year numbering system where 1 BC corresponds to year Zero, 2 BC to year -1 and so on. There is no year Zero on the Timeline, and minus simply means BC. For example year -44 is year 44 BC.

''Color'' - All events of a layer have the default color. So usually you don’t need to put anything in this field. However, if you need to give some events a different color, you put color index in this field. For this to work you need to have the needed color in the list of colours. More on that later. Also you can make the background of the time interval transparent by putting letter ’t’ into the Color field instead of an index.

===Layer metadata===
You should put metadata before the list of events, including the colours used by the events and sources (links to pages you got the information for the layer from).

The layer with metadata may look something like this:

[[File:ColoredEventsSourceCode.png|500px]]

Here is the text version that you can copy:

<blockquote><poem><nowiki>
colors:
#2683a9
#ee9c42
sources:
Hannibal
https://google.com|google
events:
event or default color;;;;05.18.1978;;
another event or default color;;;;1978;1982;
orange event;;;;1978;1982;1
</nowiki></poem></blockquote>

This code produces these events on the timeline:

[[File:ColoredEvents.png|400px]]

To pick colors use the color picker:

[[File:ColorPicker.png|400px]]

After selecting the color in the picker copy the hex code of that color and paste it into the list of colors in the Editor.

''Colors'' in the list have implicit indices that start with 0. The 0th color (the first color in the list) is the default color of the layer. Once you have specified it, all the events will have that color. To use other colours in the list you specify their indices in the Color field of the event you want to apply that color to. Notice in the example how I use index 1 in the orange event: <code>orange event;;;;1978;1982;1</code>

''Sources'' are just page names (if you link to Wikipedia pages) or full urls starting with http or https. When there is only one source page specified, you get a button ‘Source’ in the Library next to the name of the layer. Clicking this button will open a source page in the new tab. If there are more than one page specified, you get a button ‘Sources’ instead. Clicking this button opens a popup with a list of links to the pages. 

If you want the text in links to differ from the title of the page on Wikipedia or url for pages on other sites, specify the text after vertical line. This syntax can be seen in the example.

Notice, that once you have sources and or colors specified, you have to put ‘events:’  before the list of events.

After the list of events there should be a line: <code><nowiki>[[Category:History Timeline Page]]</nowiki></code>. It is used to easily download all the folder and layer pages. That's how I make backups. I made it so that without this line the layer or folder simply won't work. The good news is that this line is added into the Editor automatically for you. Just don't forget to copy it with all the other information when adding data to the server.

==The Parser==
In this article we did all the manipulations with data manually just to teach you the data format. That’s not how you usually create layers for the Timeline though. There is a program called Parser that greatly facilitates the creation of layers. You can learn how to use it from this [[Documentation:How to use the Parser|article]].

==Uploading data to the server==
Once your layer is created and tested, you can upload it to the server. You need to create a corresponding page on the server. For layers this page should be in the ''HistoryTimelineLayer'' namespace. There are two ways you can create a page on the server. One is hard and not recommended. The other is easy.

The hard way looks like this. You go to the site and in the search field enter the title of the page you want to create (don’t forget the namespace). 

[[File:LayerNameInSearchField.png]]

In the search results you will see the red link because such article doesn’t exist yet.

[[File:LayerNameInSearchResults.png]]

Click that link. Now you can paste the layer data and save it.

[[File:CreateNewLayer.png]]

The easy (and recommended) way looks like this. You type the name of the layer (without the namespace) in the top input field of the Editor. 

[[File:CreateNewLayerInEditor.png]]

You then click ''Create layer'' button. This will send you directly to the article creation page with the correct title where you can paste the layer data.

==Adding the layer to the Library==
Now that the layer is created on the server you need to make it accessible from the Timeline. To do it you need to add it to the Library. Open the Library and go to Sandbox folder. Make sure that the Cache and Edit buttons are visible. If not, use Menu to make them visible. Click the Edit button next to the ''Add your layers here'' folder. 

[[File:AddYourLayersHereInLibrary.png]]

Now you can add a reference to your layer in the list. 

[[File:AddYourLayersHereContents.png]]

The data format for layer reference is simple.

[[File:DataFormatLayer.png]]

''Visible text'' - is usually the name of the page containing layer data. 

''Link'' - if the actual name of the text differs from the visible text, specify full name of the article here.

''Is list'' - This field is used for layers presented as a list of time intervals that you can toggle individually. 

[[File:LayerAsList.png]]

If you want to specify that your layer should be viewed this way, put an <code>l</code> (lowercase L) in this field (for example: <code>My new layer;;l</code>). Otherwise leave the field empty.

==Don’t forget to clear cache==
After you add your layer to the Library most likely you won’t see any changes. That’s because the program uses the cached version of ''Add your layers here'' folder. To fix this click the ''Clear cache'' button next to the name of this folder.