@powerhousedao/academy 5.0.0-staging.9 → 5.0.1-staging.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.vscode/settings.json +1 -1
- package/CHANGELOG.md +415 -0
- package/README.md +3 -3
- package/babel.config.js +1 -1
- package/blog/BeyondCommunication-ABlueprintForDevelopment.md +25 -24
- package/blog/TheChallengeOfChange.md +21 -21
- package/docs/academy/01-GetStarted/00-ExploreDemoPackage.mdx +67 -30
- package/docs/academy/01-GetStarted/01-CreateNewPowerhouseProject.md +38 -21
- package/docs/academy/01-GetStarted/02-DefineToDoListDocumentModel.md +24 -19
- package/docs/academy/01-GetStarted/03-ImplementOperationReducers.md +44 -41
- package/docs/academy/01-GetStarted/04-BuildToDoListEditor.md +10 -10
- package/docs/academy/01-GetStarted/05-VetraStudio.md +164 -0
- package/docs/academy/01-GetStarted/06-ReactorMCP.md +58 -0
- package/docs/academy/01-GetStarted/home.mdx +185 -90
- package/docs/academy/01-GetStarted/images/Modules.png +0 -0
- package/docs/academy/01-GetStarted/images/VetraStudioDrive.png +0 -0
- package/docs/academy/01-GetStarted/styles.module.css +5 -5
- package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/01-Prerequisites.md +46 -18
- package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/02-StandardDocumentModelWorkflow.md +118 -68
- package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/03-BuilderTools.md +75 -33
- package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/_category_.json +6 -6
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/01-WhatIsADocumentModel.md +30 -21
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/02-SpecifyTheStateSchema.md +41 -37
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/03-SpecifyDocumentOperations.md +29 -25
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/04-UseTheDocumentModelGenerator.md +36 -37
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/05-ImplementDocumentReducers.md +128 -109
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/06-ImplementDocumentModelTests.md +95 -86
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/07-ExampleToDoListRepository.md +7 -9
- package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/_category_.json +6 -6
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/01-BuildingDocumentEditors.md +65 -47
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/02-ConfiguringDrives.md +77 -62
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/03-BuildingADriveExplorer.md +360 -349
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/00-DocumentToolbar.mdx +16 -10
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/01-OperationHistory.md +10 -7
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/02-RevisionHistoryTimeline.md +25 -17
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/_category_.json +6 -6
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-Authorization/01-RenownAuthenticationFlow.md +14 -7
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-Authorization/02-Authorization.md +0 -1
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-Authorization/_category_.json +5 -5
- package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/_category_.json +1 -1
- package/docs/academy/02-MasteryTrack/04-WorkWithData/01-GraphQLAtPowerhouse.md +45 -33
- package/docs/academy/02-MasteryTrack/04-WorkWithData/02-UsingTheAPI.mdx +61 -18
- package/docs/academy/02-MasteryTrack/04-WorkWithData/03-UsingSubgraphs.md +50 -54
- package/docs/academy/02-MasteryTrack/04-WorkWithData/04-analytics-processor.md +126 -110
- package/docs/academy/02-MasteryTrack/04-WorkWithData/05-RelationalDbProcessor.md +75 -45
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/GraphQL References/QueryingADocumentWithGraphQL.md +23 -21
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/best-practices.md +9 -9
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/graphql/index.md +11 -23
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/graphql/integration.md +25 -9
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/intro.md +10 -10
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/typescript/benchmarks.md +1 -1
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/typescript/index.md +16 -11
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/typescript/memory.md +6 -5
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/typescript/schema.md +2 -2
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/typescript/utilities.md +7 -5
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/use-cases/maker.md +32 -58
- package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/use-cases/processors.md +1 -1
- package/docs/academy/02-MasteryTrack/04-WorkWithData/07-drive-analytics.md +105 -71
- package/docs/academy/02-MasteryTrack/04-WorkWithData/_ARCHIVE-AnalyticsProcessorTutorial/_01-SetupBuilderEnvironment.md +22 -0
- package/docs/academy/02-MasteryTrack/04-WorkWithData/_ARCHIVE-AnalyticsProcessorTutorial/_02-CreateNewPowerhouseProject.md +9 -8
- package/docs/academy/02-MasteryTrack/04-WorkWithData/_ARCHIVE-AnalyticsProcessorTutorial/_03-GenerateAnAnalyticsProcessor.md +28 -32
- package/docs/academy/02-MasteryTrack/04-WorkWithData/_ARCHIVE-AnalyticsProcessorTutorial/_04-UpdateAnalyticsProcessor.md +25 -26
- package/docs/academy/02-MasteryTrack/04-WorkWithData/_ARCHIVE-AnalyticsProcessorTutorial/_category_.json +1 -1
- package/docs/academy/02-MasteryTrack/04-WorkWithData/_category_.json +7 -7
- package/docs/academy/02-MasteryTrack/05-Launch/01-IntroductionToPackages.md +3 -4
- package/docs/academy/02-MasteryTrack/05-Launch/02-PublishYourProject.md +69 -45
- package/docs/academy/02-MasteryTrack/05-Launch/03-SetupEnvironment.md +70 -40
- package/docs/academy/02-MasteryTrack/05-Launch/04-ConfigureEnvironment.md +1 -0
- package/docs/academy/02-MasteryTrack/05-Launch/_category_.json +7 -7
- package/docs/academy/02-MasteryTrack/_category_.json +6 -6
- package/docs/academy/03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md +5 -3
- package/docs/academy/03-ExampleUsecases/Chatroom/03-DefineChatroomDocumentModel.md +38 -37
- package/docs/academy/03-ExampleUsecases/Chatroom/04-ImplementOperationReducers.md +45 -41
- package/docs/academy/03-ExampleUsecases/Chatroom/05-ImplementChatroomEditor.md +14 -14
- package/docs/academy/03-ExampleUsecases/Chatroom/06-LaunchALocalReactor.md +6 -6
- package/docs/academy/03-ExampleUsecases/Chatroom/_category_.json +1 -1
- package/docs/academy/04-APIReferences/00-PowerhouseCLI.md +143 -48
- package/docs/academy/04-APIReferences/01-ReactHooks.md +177 -129
- package/docs/academy/04-APIReferences/04-RelationalDatabase.md +121 -113
- package/docs/academy/04-APIReferences/05-PHDocumentMigrationGuide.md +48 -41
- package/docs/academy/04-APIReferences/_category_.json +6 -6
- package/docs/academy/05-Architecture/00-PowerhouseArchitecture.md +1 -2
- package/docs/academy/05-Architecture/01-WorkingWithTheReactor.md +11 -8
- package/docs/academy/05-Architecture/05-DocumentModelTheory/_category_.json +1 -1
- package/docs/academy/05-Architecture/_category_.json +6 -6
- package/docs/academy/06-ComponentLibrary/00-DocumentEngineering.md +25 -23
- package/docs/academy/06-ComponentLibrary/02-CreateCustomScalars.md +105 -93
- package/docs/academy/06-ComponentLibrary/03-IntegrateIntoAReactComponent.md +1 -0
- package/docs/academy/06-ComponentLibrary/_category_.json +7 -7
- package/docs/academy/07-Cookbook.md +268 -35
- package/docs/academy/08-Glossary.md +7 -1
- package/docs/bookofpowerhouse/01-Overview.md +2 -2
- package/docs/bookofpowerhouse/02-GeneralFrameworkAndPhilosophy.md +1 -7
- package/docs/bookofpowerhouse/03-PowerhouseSoftwareArchitecture.md +10 -7
- package/docs/bookofpowerhouse/04-DevelopmentApproaches.md +10 -4
- package/docs/bookofpowerhouse/05-SNOsandANewModelForOSSandPublicGoods.md +23 -30
- package/docs/bookofpowerhouse/06-SNOsInActionAndPlatformEconomies.md +0 -7
- package/docusaurus.config.ts +64 -66
- package/package.json +9 -7
- package/scripts/generate-combined-cli-docs.ts +43 -13
- package/sidebars.ts +2 -0
- package/src/components/HomepageFeatures/index.tsx +171 -78
- package/src/components/HomepageFeatures/styles.module.css +1 -2
- package/src/css/custom.css +89 -89
- package/src/pages/_archive-homepage.tsx +17 -16
- package/src/theme/DocCardList/index.tsx +9 -8
- package/static.json +6 -6
- package/tsconfig.tsbuildinfo +1 -0
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
## Let's get started
|
|
4
4
|
|
|
5
|
-
To give you a quick idea of how the Powerhouse ecosystem operates on document models and packages, why don't you try installing a package?
|
|
6
|
-
We will show you how to install the Powerhouse command-line tool `ph-cmd` and then use it to install a pre-built demo package
|
|
5
|
+
To give you a quick idea of how the Powerhouse ecosystem operates on document models and packages, why don't you try installing a package?
|
|
6
|
+
We will show you how to install the Powerhouse command-line tool `ph-cmd` and then use it to install a pre-built demo package containing a document model, an editor, and a drive app.
|
|
7
7
|
|
|
8
8
|
## Step 1: Install the Powerhouse CLI
|
|
9
9
|
|
|
@@ -18,7 +18,7 @@ Verify the installation:
|
|
|
18
18
|
|
|
19
19
|
```bash
|
|
20
20
|
ph-cmd --version
|
|
21
|
-
```
|
|
21
|
+
```
|
|
22
22
|
|
|
23
23
|
## Step 2: Install the to-do list demo package
|
|
24
24
|
|
|
@@ -73,27 +73,34 @@ This command downloads and sets up the `@powerhousedao/todo-demo-package`, makin
|
|
|
73
73
|
|
|
74
74
|
</details>
|
|
75
75
|
|
|
76
|
-
|
|
77
|
-
You have now successfully installed `ph-cmd` and added your first package!
|
|
76
|
+
You have now successfully installed `ph-cmd` and added your first package!
|
|
78
77
|
|
|
79
78
|
## Step 3: Run the connect app in studio mode
|
|
79
|
+
|
|
80
80
|
To run the package locally in Connect Studio (our collaboration and contributor app), run:
|
|
81
81
|
|
|
82
82
|
```bash
|
|
83
83
|
ph connect
|
|
84
84
|
```
|
|
85
|
-
|
|
85
|
+
|
|
86
|
+
Click the returned localhost URL and you should see Connect Studio appear in your browser.
|
|
87
|
+
|
|
86
88
|
<figure className="image-container">
|
|
87
89
|
<img src={require("./images/Connect.png").default} alt="Connect Home" />
|
|
88
90
|
<figcaption>The Powerhouse Connect Studio interface.</figcaption>
|
|
89
91
|
</figure>
|
|
90
92
|
|
|
91
|
-
When you
|
|
92
|
-
Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, which contains not only a **Document Model** and its accompanying editor but also a **Drive App** specific to the to-do document model.
|
|
93
|
+
When you click the settings wheel in the bottom right corner, you'll get access to the **Package Manager**.
|
|
94
|
+
Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, which contains not only a **Document Model** and its accompanying editor but also a **Drive App** specific to the to-do document model.
|
|
93
95
|
|
|
94
96
|
<figure className="image-container">
|
|
95
|
-
<img
|
|
96
|
-
|
|
97
|
+
<img
|
|
98
|
+
src={require("./images/Packagemanager.png").default}
|
|
99
|
+
alt="Package Manager"
|
|
100
|
+
/>
|
|
101
|
+
<figcaption>
|
|
102
|
+
The Package Manager showing the installed todo-demo-package.
|
|
103
|
+
</figcaption>
|
|
97
104
|
</figure>
|
|
98
105
|
|
|
99
106
|
## Step 4: Create a todo list document
|
|
@@ -123,27 +130,43 @@ Now move into the drive you've just created:
|
|
|
123
130
|
- You'll see a statistics widget that counts the open to-dos
|
|
124
131
|
- After closing the document, look at the To-do Drive App interface—you'll see that it tracks your tasks and displays a progress bar
|
|
125
132
|
|
|
133
|
+
This is an example of the **usefulness and impact of Drive Apps**.
|
|
134
|
+
They offer a customized interface that works well with the different documents inside your drive.
|
|
135
|
+
Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
|
|
136
|
+
|
|
126
137
|
<figure className="image-container">
|
|
127
|
-
<img
|
|
128
|
-
|
|
138
|
+
<img
|
|
139
|
+
src={require("./images/TodoDriveApp.png").default}
|
|
140
|
+
alt="Todo Drive App"
|
|
141
|
+
/>
|
|
142
|
+
<figcaption>A list of todos in the custom todo drive app.</figcaption>
|
|
129
143
|
</figure>
|
|
130
144
|
|
|
131
|
-
A key feature
|
|
145
|
+
A key feature of Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when.
|
|
132
146
|
|
|
133
147
|
<figure className="image-container">
|
|
134
|
-
<img
|
|
135
|
-
|
|
148
|
+
<img
|
|
149
|
+
src={require("./images/OperationsHistoryButton.png").default}
|
|
150
|
+
alt="Operations History Button"
|
|
151
|
+
/>
|
|
152
|
+
<figcaption>
|
|
153
|
+
You can find the button to visit the operations history in the document model toolbar
|
|
154
|
+
</figcaption>
|
|
136
155
|
</figure>
|
|
137
156
|
|
|
138
157
|
<figure className="image-container">
|
|
139
|
-
<img
|
|
140
|
-
|
|
158
|
+
<img
|
|
159
|
+
src={require("./images/OperationsHistory.png").default}
|
|
160
|
+
alt="Operations History"
|
|
161
|
+
/>
|
|
162
|
+
<figcaption>
|
|
163
|
+
Example of the operations history for a document, showing all modifications
|
|
164
|
+
made to it in a list.{" "}
|
|
165
|
+
</figcaption>
|
|
141
166
|
</figure>
|
|
142
167
|
|
|
143
168
|
Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
|
|
144
169
|
|
|
145
|
-
This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
|
|
146
|
-
|
|
147
170
|
## Step 5: Enable operation signing and verification through Renown
|
|
148
171
|
|
|
149
172
|
Renown is Powerhouse's **decentralized identity and reputation system** designed to address the challenge of trust within open organizations, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities.
|
|
@@ -152,13 +175,15 @@ Renown is Powerhouse's **decentralized identity and reputation system** designed
|
|
|
152
175
|
When signing in with Renown, use an Ethereum or blockchain address that can function as your 'identity', as this address will accrue more experience and history over time.
|
|
153
176
|
:::
|
|
154
177
|
|
|
155
|
-
### 5.1 Click the renown icon and connect your
|
|
178
|
+
### 5.1 Click the renown icon and connect your Ethereum identity
|
|
156
179
|
|
|
157
180
|
"**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key.
|
|
158
181
|
|
|
159
182
|
<figure className="image-container">
|
|
160
183
|
<img src={require("./images/RenownLogin.png").default} alt="Renown Login" />
|
|
161
|
-
<figcaption>
|
|
184
|
+
<figcaption>
|
|
185
|
+
The Renown login screen, prompting for a signature from a wallet.
|
|
186
|
+
</figcaption>
|
|
162
187
|
</figure>
|
|
163
188
|
|
|
164
189
|
### 5.2 Authorize Connect to sign document edits on your behalf
|
|
@@ -166,12 +191,20 @@ When signing in with Renown, use an Ethereum or blockchain address that can func
|
|
|
166
191
|
This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier.
|
|
167
192
|
|
|
168
193
|
<figure className="image-container">
|
|
169
|
-
<img
|
|
170
|
-
|
|
194
|
+
<img
|
|
195
|
+
src={require("./images/ConnectAddress.png").default}
|
|
196
|
+
alt="Connect Address for DID"
|
|
197
|
+
/>
|
|
198
|
+
<figcaption>
|
|
199
|
+
A newly generated DID and address shown within the Connect interface.
|
|
200
|
+
</figcaption>
|
|
171
201
|
</figure>
|
|
172
202
|
|
|
173
203
|
<figure className="image-container">
|
|
174
|
-
<img
|
|
204
|
+
<img
|
|
205
|
+
src={require("./images/LoginComplete.png").default}
|
|
206
|
+
alt="Renown Login Complete"
|
|
207
|
+
/>
|
|
175
208
|
<figcaption>Confirmation of a successful login with Renown.</figcaption>
|
|
176
209
|
</figure>
|
|
177
210
|
|
|
@@ -182,16 +215,20 @@ By leveraging this system, every operation or modification made to a document is
|
|
|
182
215
|
Now, return to your to-do list and make some additional changes. You'll notice that these operations are now signed with your Renown identity, making every action traceable and verifiable in the operations history.
|
|
183
216
|
|
|
184
217
|
<figure className="image-container">
|
|
185
|
-
<img
|
|
186
|
-
|
|
218
|
+
<img
|
|
219
|
+
src={require("./images/OperationsHistorySignature.png").default}
|
|
220
|
+
alt="Operation History Signature"
|
|
221
|
+
/>
|
|
222
|
+
<figcaption>
|
|
223
|
+
Your DID is now signing the operations that are being added to the history.
|
|
224
|
+
</figcaption>
|
|
187
225
|
</figure>
|
|
188
226
|
|
|
189
227
|
## Step 6: Export a document
|
|
190
228
|
|
|
191
|
-
Export the document as a `.phd` (Powerhouse Document) file using the export button in the document toolbar at the top. In this toolbar, you will find all available functionality for your documents. The `.phd` file can be sent through any of your preferred channels to other users on your network.
|
|
229
|
+
Export the document as a `.phd` (Powerhouse Document) file using the export button in the document toolbar at the top. In this toolbar, you will find all available functionality for your documents. The `.phd` file can be sent through any of your preferred channels to other users on your network.
|
|
192
230
|
|
|
193
|
-
### Up next
|
|
231
|
+
### Up next
|
|
194
232
|
|
|
195
|
-
Now that you have explored a Powerhouse package and discovered its basic functionalities, it is time to start building your own.
|
|
233
|
+
Now that you have explored a Powerhouse package and discovered its basic functionalities, it is time to start building your own.
|
|
196
234
|
Our next tutorial focuses on creating a simple to-do list document and will introduce you to the world of **Document Models**.
|
|
197
|
-
|
|
@@ -1,25 +1,32 @@
|
|
|
1
1
|
# Create a new to-do list document
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
4
|
+
|
|
5
|
+
This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.
|
|
6
|
+
A Powerhouse project primarily consists of a document model and its editor.
|
|
7
|
+
As your projects use-case expands you can add data-integrations or a specific drive-app as seen in the demo package.
|
|
8
|
+
|
|
9
|
+
For todays purpose, you'll be using Connect, our user-centric collaboration tool and Vetra Studio, the builder tooling through which developers can access and manage specifications of their project.
|
|
7
10
|
|
|
8
11
|
## Prerequisites
|
|
9
|
-
|
|
10
|
-
-
|
|
12
|
+
|
|
13
|
+
- Powerhouse CLI installed: `pnpm install -g ph-cmd` or `npm install -g ph-cmd --legacy-peer-deps`
|
|
14
|
+
- node.js 22 and a package manager (pnpm or npm) installed
|
|
11
15
|
- Visual Studio Code (or your preferred IDE)
|
|
12
16
|
- Terminal/Command Prompt access
|
|
13
17
|
|
|
14
18
|
If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/MasteryTrack/BuilderEnvironment/Prerequisites)
|
|
15
19
|
|
|
16
20
|
## Quick start
|
|
21
|
+
|
|
17
22
|
Create a new Powerhouse project with a single command:
|
|
23
|
+
|
|
18
24
|
```bash
|
|
19
25
|
ph init
|
|
20
26
|
```
|
|
21
27
|
|
|
22
28
|
## Before you begin
|
|
29
|
+
|
|
23
30
|
1. Open your terminal (either your system terminal or IDE's integrated terminal)
|
|
24
31
|
2. Optionally, create a folder first to keep your Powerhouse projects:
|
|
25
32
|
|
|
@@ -27,32 +34,38 @@ ph init
|
|
|
27
34
|
mkdir ph-projects
|
|
28
35
|
cd ph-projects
|
|
29
36
|
```
|
|
37
|
+
|
|
30
38
|
3. Ensure you're in the correct directory before running the `ph init` command.
|
|
31
|
-
In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
|
|
32
|
-
|
|
39
|
+
In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
|
|
40
|
+
|
|
41
|
+
````bash
|
|
33
42
|
you@yourmachine:~/ph-projects % ph init
|
|
34
43
|
|
|
35
44
|
? What is the project name? ‣ getting-started
|
|
36
|
-
```
|
|
45
|
+
```
|
|
37
46
|
|
|
38
|
-
|
|
47
|
+
|
|
48
|
+
Once the project is created, you will see the following output:
|
|
39
49
|
```bash
|
|
40
50
|
Initialized empty Git repository in /Users/you/ph-projects/getting-started/.git/
|
|
41
|
-
The installation is done!
|
|
51
|
+
The installation is done!
|
|
42
52
|
```
|
|
43
53
|
|
|
44
|
-
|
|
54
|
+
Navigate to the newly created project directory:
|
|
45
55
|
```bash
|
|
46
56
|
cd getting-started
|
|
47
57
|
```
|
|
48
|
-
|
|
49
|
-
|
|
58
|
+
|
|
59
|
+
## Develop a single document model in Connect
|
|
60
|
+
|
|
61
|
+
Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
|
|
62
|
+
Run the following command to start the Connect application:
|
|
50
63
|
|
|
51
64
|
```bash
|
|
52
65
|
ph connect
|
|
53
66
|
```
|
|
54
67
|
|
|
55
|
-
|
|
68
|
+
The Connect application will start and you will see the following output:
|
|
56
69
|
|
|
57
70
|
```bash
|
|
58
71
|
➜ Local: http://localhost:3000/
|
|
@@ -60,17 +73,21 @@ In the terminal, you will be asked to enter the project name. Fill in the projec
|
|
|
60
73
|
➜ press h + enter to show help
|
|
61
74
|
```
|
|
62
75
|
|
|
63
|
-
|
|
76
|
+
A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
|
|
64
77
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
78
|
+
You will see your local drive and a button to create a new drive.
|
|
79
|
+
If you local drive is not present navigate into Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.
|
|
80
|
+
Clear the storage of your localhost application as it might has an old session cached.
|
|
68
81
|
|
|
69
|
-
4. Move into your local drive.
|
|
70
|
-
Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page.
|
|
82
|
+
4. Move into your local drive.
|
|
83
|
+
Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page.
|
|
71
84
|
|
|
72
85
|
If you've followed the steps correctly, you'll have an empty document where you can define the **'Document Specifications'**.
|
|
73
86
|
|
|
87
|
+
## Develop a package in Vetra Studio
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
|
|
74
91
|
## Up next
|
|
75
92
|
|
|
76
|
-
In the next tutorials, you will learn how to specify, add code and build an editor for your document model and export it to be used in your Powerhouse package.
|
|
93
|
+
In the next tutorials, you will learn how to specify, add code and build an editor for your document model and export it to be used in your Powerhouse package.
|
|
@@ -1,12 +1,14 @@
|
|
|
1
|
-
# Write the document specification
|
|
1
|
+
# Write the document specification
|
|
2
2
|
|
|
3
3
|
In this tutorial, you will learn how to define the specifications for a **To-do List** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
|
|
4
4
|
If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.
|
|
5
5
|
|
|
6
6
|
Before you start, make sure you have the Connect application running locally with the command:
|
|
7
|
+
|
|
7
8
|
```bash
|
|
8
9
|
ph connect
|
|
9
10
|
```
|
|
11
|
+
|
|
10
12
|
The Connect application will start and you will see the following output:
|
|
11
13
|
|
|
12
14
|
```bash
|
|
@@ -17,11 +19,11 @@ The Connect application will start and you will see the following output:
|
|
|
17
19
|
|
|
18
20
|
## To-do list document specification
|
|
19
21
|
|
|
20
|
-
Likely you have called your project 'ToDoList'.
|
|
21
|
-
If you've used a different name, please create a new document specification named 'ToDoList'.
|
|
22
|
-
**Pay close attention to capitalization, as it influences our code.**
|
|
22
|
+
Likely you have called your project 'ToDoList'.
|
|
23
|
+
If you've used a different name, please create a new document specification named 'ToDoList'.
|
|
24
|
+
**Pay close attention to capitalization, as it influences our code.**
|
|
23
25
|
|
|
24
|
-
We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.
|
|
26
|
+
We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.
|
|
25
27
|
Below, you can see the SDL for the `To-do List` document model.
|
|
26
28
|
|
|
27
29
|
:::info
|
|
@@ -45,9 +47,8 @@ type ToDoItem {
|
|
|
45
47
|
checked: Boolean!
|
|
46
48
|
}
|
|
47
49
|
```
|
|
48
|
-
</details>
|
|
49
|
-
|
|
50
50
|
|
|
51
|
+
</details>
|
|
51
52
|
|
|
52
53
|
<details>
|
|
53
54
|
<summary>Operations schema of our simplified to-do list</summary>
|
|
@@ -59,34 +60,37 @@ input AddTodoItemInput {
|
|
|
59
60
|
}
|
|
60
61
|
|
|
61
62
|
# Defines a GraphQL input type for updating a to-do item
|
|
63
|
+
|
|
62
64
|
input UpdateTodoItemInput {
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
65
|
+
id: ID!
|
|
66
|
+
text: String
|
|
67
|
+
checked: Boolean
|
|
66
68
|
}
|
|
67
69
|
|
|
68
70
|
# Defines a GraphQL input type for deleting a to-do item
|
|
71
|
+
|
|
69
72
|
input DeleteTodoItemInput {
|
|
70
|
-
|
|
73
|
+
id: ID!
|
|
71
74
|
}
|
|
72
|
-
|
|
75
|
+
|
|
76
|
+
````
|
|
73
77
|
</details>
|
|
74
78
|
|
|
75
79
|
## Define the document model specification
|
|
76
80
|
|
|
77
|
-
To be able to define the document model, you need to open the document model editor in Connect.
|
|
81
|
+
To be able to define the document model, you need to open the document model editor in Connect.
|
|
78
82
|
|
|
79
83
|
### The steps below show you how to do this:
|
|
80
84
|
|
|
81
85
|
1. In the Connect application, click on **'document model'** to open the document model specification editor.
|
|
82
|
-
2. Name your document model '**ToDoList**' in the Connect application, paying close attention to capitalization.
|
|
83
|
-
3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields.
|
|
86
|
+
2. Name your document model '**ToDoList**' in the Connect application, paying close attention to capitalization.
|
|
87
|
+
3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields.
|
|
84
88
|
|
|
85
89
|
In the **Document Type** field, type `powerhouse/todolist`. This defines the new type of document that will be created with this document model specification.
|
|
86
|
-
|
|
90
|
+
|
|
87
91
|

|
|
88
92
|
|
|
89
|
-
4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language.
|
|
93
|
+
4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language.
|
|
90
94
|
5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `to_do_list`. Press enter.
|
|
91
95
|
6. Now there is a new field, called `Add operation`. Here you will have to add each input operation to the module, one by one.
|
|
92
96
|
7. Inside the `Add operation` field, type `ADD_TODO_ITEM` and press enter. A small editor will appear underneath it, with an empty input type that you have to fill. Copy the first input type from the [Operations Schema](#operations-schema) section and paste it in the editor. The editor should look like this:
|
|
@@ -106,6 +110,7 @@ Check below screenshot for the complete implementation:
|
|
|
106
110
|
|
|
107
111
|

|
|
108
112
|
|
|
109
|
-
### Up next: reducers
|
|
113
|
+
### Up next: reducers
|
|
114
|
+
|
|
115
|
+
Up next, you'll learn how to implement the runtime logic and components that will use the `ToDoList` document model specification you've just created and exported.
|
|
110
116
|
|
|
111
|
-
Up next, you'll learn how to implement the runtime logic and components that will use the `ToDoList` document model specification you've just created and exported.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Implement the document model
|
|
2
2
|
|
|
3
|
-
In this section, we will implement and test the operation reducers for the **To-do List** document model. For this, you have to export the document model specification from the Connect application and import it into your Powerhouse project directory.
|
|
3
|
+
In this section, we will implement and test the operation reducers for the **To-do List** document model. For this, you have to export the document model specification from the Connect application and import it into your Powerhouse project directory.
|
|
4
4
|
|
|
5
5
|
To export the document model specification, follow the steps in the [Define ToDoList Document Model](/academy/GetStarted/DefineToDoListDocumentModel) section.
|
|
6
6
|
|
|
@@ -9,11 +9,12 @@ To export the document model specification, follow the steps in the [Define ToDo
|
|
|
9
9
|
Reducers are a core concept in Powerhouse document models. They implement the state transition logic for each operation defined in your schema.
|
|
10
10
|
|
|
11
11
|
:::info
|
|
12
|
-
**Connection to schema definition language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema?
|
|
12
|
+
**Connection to schema definition language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema?
|
|
13
13
|
The reducers provide the actual implementation of what happens when those operations are performed.
|
|
14
14
|
:::
|
|
15
15
|
|
|
16
|
-
To import the document model specification into your Powerhouse project, you can either:
|
|
16
|
+
To import the document model specification into your Powerhouse project, you can either:
|
|
17
|
+
|
|
17
18
|
- Copy and paste the file directly into the root of your Powerhouse project.
|
|
18
19
|
- Or drag and drop the file into the Powerhouse project directory in the VSCode editor as seen in the image below:
|
|
19
20
|
|
|
@@ -23,8 +24,7 @@ Either step will import the document model specification into your Powerhouse pr
|
|
|
23
24
|
|
|
24
25
|
## In your project directory
|
|
25
26
|
|
|
26
|
-
The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside VSCode open as well.
|
|
27
|
-
|
|
27
|
+
The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside VSCode open as well.
|
|
28
28
|
|
|
29
29
|
To write the operation reducers of the **To-do List** document model, you need to generate the document model code from the document model specification file you have exported into the Powerhouse project directory.
|
|
30
30
|
|
|
@@ -45,7 +45,6 @@ Open the `to-do-list.ts` file and you should see the code that needs to be fille
|
|
|
45
45
|
1. Copy and paste the code below into the `to-do-list.ts` file in the `reducers` folder.
|
|
46
46
|
2. Save the file.
|
|
47
47
|
|
|
48
|
-
|
|
49
48
|
<details>
|
|
50
49
|
<summary>Operation Reducers</summary>
|
|
51
50
|
```typescript
|
|
@@ -54,31 +53,31 @@ import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
|
|
|
54
53
|
// REMARKS: This is our main reducer object that implements all operations defined in the schema.
|
|
55
54
|
// The ToDoListToDoListOperations type is auto-generated from our SDL and ensures type safety.
|
|
56
55
|
export const reducer: ToDoListToDoListOperations = {
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
56
|
+
// REMARKS: The addTodoItemOperation adds a new item to our todolist.
|
|
57
|
+
// - state: The current document state that we can modify
|
|
58
|
+
// - action: Contains the operation type and input data from the client
|
|
59
|
+
// - dispatch: Function to trigger additional operations (not used here)
|
|
60
|
+
addTodoItemOperation(state, action, dispatch) {
|
|
61
|
+
// REMARKS: While this looks like we're directly mutating state, Powerhouse
|
|
62
|
+
// handles immutability behind the scenes, creating a new state object.
|
|
63
|
+
state.items.push({
|
|
64
|
+
id: action.input.id, // Using the client-provided ID
|
|
65
|
+
text: action.input.text, // Setting the todo text from input
|
|
66
|
+
checked: false, // New items always start unchecked
|
|
67
|
+
});
|
|
68
|
+
},
|
|
69
|
+
|
|
70
|
+
// REMARKS: The updateTodoItemOperation modifies an existing todo item.
|
|
71
|
+
// It handles partial updates, allowing only specific fields to be updated.
|
|
72
|
+
updateTodoItemOperation(state, action, dispatch) {
|
|
73
|
+
// REMARKS: First find the item we want to update by its ID
|
|
74
|
+
const item = state.items.find(item => item.id === action.input.id);
|
|
75
|
+
|
|
77
76
|
// REMARKS: Proper error handling if item doesn't exist
|
|
78
77
|
if (!item) {
|
|
79
78
|
throw new Error(`Item with id ${action.input.id} not found`);
|
|
80
79
|
}
|
|
81
|
-
|
|
80
|
+
|
|
82
81
|
// REMARKS: We only update fields that were included in the input
|
|
83
82
|
// This allows for partial updates (only update what was provided)
|
|
84
83
|
if (action.input.text) {
|
|
@@ -87,17 +86,19 @@ export const reducer: ToDoListToDoListOperations = {
|
|
|
87
86
|
if (typeof action.input.checked === 'boolean') {
|
|
88
87
|
item.checked = action.input.checked;
|
|
89
88
|
}
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
89
|
+
|
|
90
|
+
},
|
|
91
|
+
|
|
92
|
+
// REMARKS: The deleteTodoItemOperation removes an item from the list.
|
|
93
|
+
// This showcases functional programming with array filters for immutable updates.
|
|
94
|
+
deleteTodoItemOperation(state, action, dispatch) {
|
|
95
|
+
// REMARKS: Create a new array containing only items that don't match the ID
|
|
96
|
+
// This is a common pattern for immutable array updates in JavaScript
|
|
97
|
+
state.items = state.items.filter(item => item.id !== action.input.id);
|
|
98
|
+
},
|
|
99
99
|
};
|
|
100
|
-
|
|
100
|
+
|
|
101
|
+
````
|
|
101
102
|
</details>
|
|
102
103
|
|
|
103
104
|
## Write the operation reducers tests
|
|
@@ -131,7 +132,7 @@ describe('Todolist Operations', () => {
|
|
|
131
132
|
it('should handle addTodoItem operation', () => {
|
|
132
133
|
// REMARKS: We create an input object matching our AddTodoItemInput schema
|
|
133
134
|
const input = { id: '1', text: 'Buy milk' };
|
|
134
|
-
|
|
135
|
+
|
|
135
136
|
// REMARKS: We apply the operation to get a new document state
|
|
136
137
|
// Note how we use the creators to generate the operation action
|
|
137
138
|
const updatedDocument = reducer(document, creators.addTodoItem(input));
|
|
@@ -174,7 +175,8 @@ describe('Todolist Operations', () => {
|
|
|
174
175
|
expect(updatedDocument.state.global.items).toHaveLength(0);
|
|
175
176
|
});
|
|
176
177
|
});
|
|
177
|
-
|
|
178
|
+
````
|
|
179
|
+
|
|
178
180
|
</details>
|
|
179
181
|
|
|
180
182
|
Now you can run the tests to make sure the operation reducers are working as expected.
|
|
@@ -192,7 +194,8 @@ Output should be as follows:
|
|
|
192
194
|
Duration 417ms (transform 79ms, setup 0ms, collect 174ms, tests 12ms, environment 0ms, prepare 158ms)
|
|
193
195
|
```
|
|
194
196
|
|
|
195
|
-
If you got the same output, you have successfully implemented the operation reducers and tests for the **To-do List** document model. Congratulations, you've successfully set up the backbone for a simple **To-do List** document.
|
|
197
|
+
If you got the same output, you have successfully implemented the operation reducers and tests for the **To-do List** document model. Congratulations, you've successfully set up the backbone for a simple **To-do List** document.
|
|
196
198
|
|
|
197
199
|
## Up next: To-do list editor
|
|
198
|
-
|
|
200
|
+
|
|
201
|
+
In the next chapter of this introduction track you will learn how to implement an editor for your document model so you can see a simple user interface for the **To-do List** document model in action.
|
|
@@ -4,7 +4,7 @@ In this chapter we will continue with the interface or editor implementation of
|
|
|
4
4
|
|
|
5
5
|
## Generate the editor template
|
|
6
6
|
|
|
7
|
-
Run the command below to generate the editor template for the **To-do List** document model.
|
|
7
|
+
Run the command below to generate the editor template for the **To-do List** document model.
|
|
8
8
|
This command reads the **To-do List** document model definition from the `document-models` folder and generates the editor template in the `editors/to-do-list` folder as `editor.tsx`.
|
|
9
9
|
|
|
10
10
|
Notice the `--editor` flag which specifies the **To-do List** document model, and the `--document-types` flag defines the document type `powerhouse/todolist`.
|
|
@@ -15,16 +15,15 @@ ph generate --editor ToDoList --document-types powerhouse/todolist
|
|
|
15
15
|
|
|
16
16
|
Once complete, navigate to the `editors/to-do-list/editor.tsx` file and open it in your editor.
|
|
17
17
|
|
|
18
|
-
|
|
19
18
|
### Editor implementation options
|
|
20
19
|
|
|
21
20
|
When building your editor component within the Powerhouse ecosystem, you have several options for styling, allowing you to leverage your preferred methods:
|
|
22
21
|
|
|
23
|
-
1. **Default HTML Styling:** Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) will render with default styles offered through the boilerplate.
|
|
22
|
+
1. **Default HTML Styling:** Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) will render with default styles offered through the boilerplate.
|
|
24
23
|
2. **Tailwind CSS:** Connect Studio comes with Tailwind CSS integrated. You can directly use Tailwind utility classes for rapid, consistent styling without writing separate CSS files.
|
|
25
24
|
3. **Custom CSS Files:** You can import traditional CSS files (`.css`) to apply custom styles or integrate existing style libraries.
|
|
26
25
|
|
|
27
|
-
Connect Studio provides a dynamic local environment, by running `ph connect` to visualize your components instantly as you build them, regardless of the styling method you choose.
|
|
26
|
+
Connect Studio provides a dynamic local environment, by running `ph connect` to visualize your components instantly as you build them, regardless of the styling method you choose.
|
|
28
27
|
Manual build steps are typically only needed when publishing packages.
|
|
29
28
|
|
|
30
29
|
## To-do List editor
|
|
@@ -189,6 +188,7 @@ export default function Editor(props: IProps) {
|
|
|
189
188
|
);
|
|
190
189
|
}
|
|
191
190
|
```
|
|
191
|
+
|
|
192
192
|
</details>
|
|
193
193
|
|
|
194
194
|
Now you can run the Connect app and see the **To-do List** editor in action.
|
|
@@ -197,22 +197,22 @@ Now you can run the Connect app and see the **To-do List** editor in action.
|
|
|
197
197
|
ph connect
|
|
198
198
|
```
|
|
199
199
|
|
|
200
|
-
In Connect, in the bottom right corner you'll find a new Document Model that you can create: **To-do List**.
|
|
200
|
+
In Connect, in the bottom right corner you'll find a new Document Model that you can create: **To-do List**.
|
|
201
201
|
Click on it to create a new To-do List document.
|
|
202
202
|
|
|
203
203
|
:::info
|
|
204
|
-
The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio.
|
|
204
|
+
The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio.
|
|
205
205
|
:::
|
|
206
206
|
|
|
207
207
|
Congratulations!
|
|
208
|
-
If you managed to follow this tutorial until this point, you have successfully implemented the **To-do List** document model with its reducer operations and editor.
|
|
208
|
+
If you managed to follow this tutorial until this point, you have successfully implemented the **To-do List** document model with its reducer operations and editor.
|
|
209
209
|
|
|
210
210
|
### Up next: Mastery Track
|
|
211
211
|
|
|
212
212
|
In the [Mastery Track chapther: Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) we guide you through the theoretics of the previous steps while created a more advanced version of the To-do List.
|
|
213
213
|
|
|
214
|
-
You will learn:
|
|
214
|
+
You will learn:
|
|
215
|
+
|
|
215
216
|
- The in's & out's of a document model.
|
|
216
217
|
- How to use UI & Scalar components from the Document Engineering system.
|
|
217
|
-
- How to build Custom Drive Apps or Drive Explorers.
|
|
218
|
-
|
|
218
|
+
- How to build Custom Drive Apps or Drive Explorers.
|