Creating your own WordWeaver
This guide assumes you have followed the steps for installing WordWeaver. You are therefore assumed to have some knowledge and understanding of Git, Command Line, and NPM. All of these tools are used in this guide
The basic layout
Before we dig in, have a look at the directory tree below. Remember to refer to this throughout this guide! It is the standard (partially redacted) structure of your WordWeaver.
If there are files in your cloned version that are not in the tree below, you do not have to worry about them unless you are very comfortable with Angular applications and want to customize your application beyond what is covered in this documentation.
.
+-- projects
| +-- word-weaver-cli
| +-- word-weaver
| +-- src
| +-- app
| +-- app
| +-- core
| +-- pages
| +-- shared
| +-- assets
| +-- data
| +-- fr
| +-- v1
| +-- conjugations.json
| +-- options.json
| +-- pronouns.json
| +-- verbs.json
| +-- i18n
| +-- data
| +-- en.json
| +-- fr.json
| +-- en.json
| +-- fr.json
| +-- wwlogo.png
| +-- config
| +-- config.fr.ts
| +-- config.ts
| +-- schema.fr.ts
| +-- schema.ts
| +-- environments
| +-- environment.prod.ts
| +-- environment.test.ts
| +-- environment.ts
| +-- scss
| +-- themes
| +-- index.html
| +-- styles.scss
+-- angular.json
+-- package.json
Generally speaking, there are four places that you will need to edit:
projects/word-weaver/src/assets/data
. This is where you will put your data for your WordWeaver. You will need four files containing all of the pronouns, verbs, conjugations, and 'options' (typically tense or aspect related inflections). Information about how to add your data can be found just below in this section.projects/word-weaver/src/config
. This is where you will define the basic configuration of your website including defining the schemas for your data.projects/word-weaver/src/assets/i18n
. This is where you will include any translations of the either the website or your data files. The guides for editing these files can be found here.projects/word-weaver/src/environments
. This is where all environment/deployment-specific configuration for your WordWeaver-UI is located. The guides for editing these files can be found here.
Adding your language data
First, we will describe the data structures and files you will need to build. To start adding your data, you need to create a folder in projects/word-weaver/src/assets/data
that is named after your language - remember the code you use here! You can also create multiple versions of your data, so by convention let's start with v1
which refers to version 1
. You should add a folders then to projects/word-weaver/src/assets/data/<your_language_code>/v1
. You'll then need to add the following files as described in the next 4 sections.
The essence of this is that you will have to update the TypeScript interfaces to match your data.If your data does not vary from the described defaults, the default interfaces will contain all sufficient information and can be left untouched. However, if your data does vary from the default that’s been described, you will have to update the associated model.
Verbs
You must have data related to the verb roots available in your WordWeaver in a projects/word-weaver/src/assets/data/<your_language_code>/v1/verbs.json
file. Your verbs should be a JSON array of objects. Minimally, each verb in your verbs array must have a unique tag
key.
tag
The tag
is the unique identifier for that verb. It must also be URL friendly, otherwise known as a slug. To be URL friendly, a slug must be restricted to certain characters
classes
The classes
key is an array of strings that are CSS class names to apply to that verb. This can be used to distinguish different verb types to the user. For more information, please visit the WordWeaver UI style customization guide.
Default Definition:
Source: projects/word-weaver/src/config/schema.tsexport interface Verb {
gloss: string;
display: string;
tag: string;
classes: string[];
}
For example, the verbs JSON file should be of the following form:
Source: projects/word-weaver/src/assets/data/fr/v1/verbs.json[
{
"tag":"aller",
}
]
Pronouns
You must have data related to pronouns available in your WordWeaver in a projects/word-weaver/src/assets/data/<your_language_code>/v1/pronouns.json
file. Your pronouns should be a JSON array of objects. Minimally, each pronoun in your pronoun array must have a unique tag
. The default for the pronouns is to accept only an agent
. To include a patient
, it should be included in the pronouns JSON file and the Conjugations related models must be updated as well (see section for details).
WordWeaver was initially created for Kanyen'kéha, an Iroquoian language. In Iroquoian languages, semantic notions of 'Agent' and "Patient" are more meaningful than purely syntactic notions of 'Subject' and 'Object'. The naming here is vestigial from that. If it is more relevant for your language to think of 'agent' as 'subject' and 'patient' as 'object' then that is fine too.
tag
The tag
is the unique identifier for that pronoun. It must also be URL friendly, otherwise known as a slug. To be URL friendly, a slug must be restricted to certain characters
Default Definition:
Source: projects/word-weaver/src/config/schema.tsexport interface Pronoun {
gender: "M" | "F" | "N" | "";
gloss: string;
number: "SG" | "PL";
role: "agent" | "patient" | "";
obj_gloss: string;
person: "1" | "2" | "3";
value: string;
position?: Number;
tag: string;
}
For example, the pronouns JSON file should be of the following form:
Source: projects/word-weaver/src/assets/data/fr/v1/pronouns.json[
{
"person": "1",
"number": "SG",
"tag": "1-sg"
}
]
Options
The 'Options' category is a catch-all category for all other types of information associated with choosing a conjugation. You must have data related to the options available in your WordWeaver in a single options.json
file. Your options should be a JSON array of objects. Minimally, each option in your options array must have a unique tag
. The default model also includes an optional type
attribute.
tag
The tag
is the unique identifier for that option. It must also be URL friendly, otherwise known as a slug. To be URL friendly, a slug must be restricted to certain characters.
type
The type
allows for categorization of options (ex. tense, aspect etc)
Default Definition:
Source: projects/word-weaver/src/config/schema.tsexport interface Option {
classes: string[];
gloss: string;
tag: string;
type?: string;
}
For example, the options JSON file should be of the following form:
Source: projects/word-weaver/src/assets/data/fr/v1/options.json[
{
"tag": "indicatif-present",
"type": "indicatif"
}
]
Conjugations
You must have data related to the conjugations available in your WordWeaver in a single conjugations.json
.
Each conjugation consists of an input
and an output
:
export interface ConjugationObject {
input: ConjugationInput;
output: Conjugation;
}
The input
is an object that includes the tag values for each related verb
, pronoun
, and option
.
export interface ConjugationInput {
root: string;
option: string;
agent: string;
}
Note that the default ConjugationInput class assumes only an agent is required for any given conjugation. If your language's conjugations may require an patient
, please be sure to add a patient
attribute to this model.
export interface ConjugationInput {
root: string;
option: string;
agent: string;
patient: string;
}
The output
is a list of morphemes:
export type ConjugationMorpheme = [
position: number,
value: string,
type: string[]
];
export type Conjugation = ConjugationMorpheme[];
Conjugation morphemes are units that can be concatenated into Tiers
. Tiers are defined in the WordWeaver UI.
For example, the conjugations JSON file should be of the following form:
Source: projects/word-weaver/src/assets/data/fr/v1/conjugations.json[
{
"input": {
"root": "courir",
"option": "conditionnel-present",
"agent": "1-sg"
},
"output": [
[0, "cour", ["root"]],
[1, "rais", ["ending"]]
]
}
]
Here, courir
must be a tag of a verb defined in verbs.json
. conditionnel-present
must be a tag of an option defined in options.json
and 1-sg
must be a tag of a pronoun defined in pronouns.json
.
If your language data is not available split up into morphemes, instead put the full value in position 0 of the output.
Configuring your WordWeaver
This section of the guide will walk you through all the various ways you can configure your WordWeaver.
You can either replace the configuration in projects/word-weaver/src/config/config.ts
or you can create an additional configuration. In order to create an additional configuration, create a sub-configuration file with your languages' ISO 639-3 code at projects/word-weaver/src/config/config.<yourlanguagecode>.ts
. Then, you will have to edit the angular.json
file to include your file replacements. Then you can run your site with npm start -- --configuration=<yourlanguagecode>
. If you make your own language configuration, it is still recommended that you copy the main projects/word-weaver/src/config/config.ts
to use as a template.
Editing the configuration in the way described in this guide assumes you have TypeScript hints in your text editor (we suggest Visual Studio Code). Without it, you might make type errors that cause WordWeaver to crash!
Tiers
As mentioned above in the conjugations section, conjugation morphemes are units that can be concatenated into Tiers
. Tiers concatenate conjugation morphemes based on a provided key. They also join them with a provided separator
value.
For example, here's a possible conjugation:
{
"input": {
"root": "courir",
"option": "conditionnel-present",
"agent": "1-sg"
},
"output": [
[0, "cour", ["root"]],
[1, "rais", ["ending"]]
]
}
Here is an example of two possible tiers that could be defined from this type of data in a WordWeaver UI:
export const TIERS: Tier[] = [
{
name: "display",
key: "value",
position: 0,
separator: ""
},
{
name: "breakdown",
key: "value",
position: 1,
separator: "-"
}
];
Here, the display
tier value would be courez
while the breakdown
tier would be cour-ez
. Because the display
tier has a position of 0 and the breakdown
tier has a position of 1, they would be displayed as follows in your WordWeaver:
courez
cour-ez
Meta
Below is a complete sample configuration of a WordWeaver-UI's Meta data. This configuration gives basic high-level information to WordWeaver that let's it know how to display your site.
export const META: Meta = {
contributors: [
{
name: "Aidan Pine",
title: "Lead Developer",
text:
"Aidan is an application development specialist on
the NRC's Indigenous Language Technology project.
You can put <b>html</b> in here! And Unicode 😃",
img: 'assets/aidanpine.jpg'
}
],
languages: [
{ label: "en", value: "en" },
{ label: "fr", value: "fr" }
],
wordmakerTempView: "default",
tableviewer: {
viewModes: ["list", "grid", "tree"],
defaultViewMode: "grid",
gridViewDefaultOrder: {
col: "option",
row: "pn",
main: "root"
}
},
logo: "assets/wwlogo.png",
copyright: {
name: "National Research Council Canada",
url: "https://nrc.canada.ca/en/node/1378"
},
links: {
github: {
display: true,
url: "https://www.github.com/roedoejet/wordweaver-UI"
},
medium: {
display: false,
url: ""
},
facebook: {
display: false,
url: ""
},
youtube: {
display: false,
url: ""
}
}
};
Now, let's break this down! The following guide to configuration separates each configurable piece and describes its type, the effect it has on the UI, and any other requirements to the configuration.
contributors
Type: Contributor[]
Effect: Adding information to the Meta.contributors
list will add that information to the list of contributors in the About Page.
Requirements: None
copyright
Type:
{
name: string;
url: string;
}
Effect: Adds the name of the copyright holder (and a link to their site) to the footer of the page
Requirements: A valid link that begins with https://
languages
Type: Language[]
Effect: The list of languages here is used in the Settings and Header to select languages. The label
is the displayed string and the value
is the internal value. We recommend this should be an ISO 639-3 value.
Requirements: Your language will not work without the proper translation files. Please follow the internationalization guide.
links
Type:
{
github: Link;
medium: Link;
facebook: Link;
youtube: Link;
}
Effect: Adds a link at Link.url
if Link.display
is equal to true
Requirements: Valid links must begin with https://
logo
Type: string
Effect: Adds a graphic to the top left of the page
Requirements: Valid links must either be valid web links starting with https://
, or paths to internal resources ex: 'assets/logo.png'
wordmaker.tempView
Type: "default" | TierNames;
Effect: Determines which value to display in the 3rd step of the WordMaker view. If default, then the option value is chosen, otherwise any declared tier name can be chosen.
Requirements: All options must produce valid conjugations to use a TierName.
tableviewer.viewModes
Type: TableviewerViewModes[]
Effect: Determines which different Tableviewer views are available. Default allowable views are list
, grid
and tree
views.
Requirements: None
Overriding App Default Settings
There are a number of variables that are kept to maintain state for your WordWeaver that have defaults.
Many of these variables are internal and shouldn't need to be edited manually. However, some, in particular language
, theme
, and autoNightMode
should be overridden as required.
See the default initial state below:
const initialBaseState: SettingsState = {
language: "en",
theme: "PURPLE-THEME--LIGHT",
autoNightMode: false,
nightTheme: NIGHT_MODE_THEME,
stickyHeader: true,
pageAnimations: true,
pageAnimationsDisabled: false,
elementsAnimations: true,
baseUrl: environment.base + environment.prefix,
testApi: false,
colors: {
primary: "rgb(255, 255, 255)",
accent: "rgb(255, 255, 255)"
},
level: environment.config.level,
highlight: environment.config.highlight,
hour: new Date().getHours()
};
Values declared here can be overridden in your configuration file in projects/word-weaver/src/config
by exporting a variable called initialSettings
.
Below is an example that overrides the language
, theme
and autoNightMode
values:
export const initialSettings: Partial<SettingsState> = {
language: "en",
theme: "DEFAULT-THEME",
autoNightMode: false
};
language
Type: "list" | "grid" | "tree"
Effect: Determines which view is shown by default.
Requirements: None
theme
Type: Theme
Effect: Determines which theme is applied by default.
Requirements: Theme names must correspond to the names of your defined theme class names in projects/word-weaver/src/styles.scss
.
Variables are written in upper case by convention.
To see how to create your own themes, please visit the theme guide.
autoNightMode
Type: boolean
Effect: Determines whether auto-night-mode is turned on or not. If turned on, a dark theme will be applied between the hours 21:00 and 7:00.
Requirements: None