This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix"); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms"); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links"); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + '
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default"); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers"); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode"); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })();
Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Docs: Add Custom Code Guide - #520

Open
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates
Open

Docs: Add Custom Code Guide#520
dericksozo wants to merge 17 commits into
mainfrom
docs/git-sync-updates

Conversation

@dericksozo

@dericksozodericksozo commented Sep 10, 2024

Copy link
Copy Markdown
Contributor

(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.

This PR takes care of #517 and #518.

… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
@dericksozodericksozo added the documentation Improvements or additions to documentation label Sep 10, 2024
@dericksozodericksozo self-assigned this Sep 10, 2024
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/how-to/add-custom-code.md Outdated
Comment threaddocs/getting-started/add-custom-code.md Outdated
3. Amplication uses a folder structure that separates customizable and non-customizable code.
4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication.
5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead of saying this- we can say that custom code can be added to all files or such.

5. Files outside the `base` folder can be safely customized and will be preserved across builds.
1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amplication can update the files in the base folder in each build, but also may update generated code in other files

1. All code in your Amplication project can be customized.
2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.

2. Amplication uses a specific folder structure to manage custom and generated code.
3. The `base` folder contains generated files that Amplication updates with each build.
4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it

```bash
git push origin main
```
1. Base files in the `base` folder are regenerated with each build.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time

Comment threaddocs/how-to/add-custom-code.md Outdated

Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again- all custom code is preserved...

Comment threaddocs/how-to/add-custom-code.md Outdated
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
1. Amplication will provide clear indications of the conflicting areas.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the known git mechanism

Comment threaddocs/how-to/add-custom-code.md Outdated
## Handling Conflicts

4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch

Comment threaddocs/how-to/add-custom-code.md Outdated
- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
- Major changes to your data model or entity structure may require manual updates to your custom code.
- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove it. I don't think it adds value here

---

# Add custom code to your services
# Understanding Custom Code in Amplication

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?

@dericksozo

dericksozo commented Sep 23, 2024

Copy link
Copy Markdown
ContributorAuthor

Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested.

My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example?

@yuval-hazaz

Copy link
Copy Markdown
Member

@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it

Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentationImprovements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@dericksozo@yuval-hazaz@PazYanoverr