Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Terminology: pages vs. components #25

Open
caolan opened this issue Feb 8, 2018 · 3 comments
Open

Terminology: pages vs. components #25

caolan opened this issue Feb 8, 2018 · 3 comments
Labels
discussion

Comments

@caolan
Copy link
Owner

caolan commented Feb 8, 2018

Magery is designed around custom HTML5 template tags that called 'components' (though sometimes confusingly referred to as templates in our docs). On the server-side these need to be placed into a full HTML document to be useful, on the client-side only the components are used.

I'm proposing we call all current templates using custom tags 'components', and we introduce a concept of 'pages' for use with server-side implementations.

A page might look something like this:

<!DOCTYPE html>
<html>
  <head>
    <title>{{ page.title }}</title>
  </head>
  <body>
    <h1>Profile</h1>
    <my-component user="{{ user }}"></my-component>
  </body>
</html>

Which makes use of a component defined like this:

<template data-tagname="my-component">
  Hello, {{ user.name }}!
</template>

In the server-side library you would call separate functions/methods/whatever to load components and pages, for example:

magery.load_components("./templates/components")
magery.load_pages("./templates/pages")

Components would be rendered using their tag name:

magery.render_component("my-component", data)

And pages would be rendered using the path to the template file:

magery.render_page("project/example.html", data)

Exactly how those server-side APIs look and how page paths are constructed will be up to server-side implementors - they can do whatever makes sense in their language.
@caolan
Copy link
Owner Author

caolan commented Feb 8, 2018

I think having two separate loading mechanisms might not be necessary. Instead of doing:

magery.load_components("./templates/components")
magery.load_pages("./templates/pages")

It could just be:

magery.load_files("./templates")

Which would populate both pages and components.

That means it would be possible for a single file to potentially define both a page and components:

<!DOCTYPE html>
<html>
  <head>
    <title>Example</title>
  </head>
  <body>
    <template data-tagname="my-component">
        Hello, {{ name }}!
    </template>
  </body>
</html>

With the above example both a page and a component (called my-component) are registered. Rendering the page would include the embedded component template.

@caolan
Copy link
Owner Author

caolan commented Feb 8, 2018

In which case pages should just be referred to as files so it's clear you're simply rendering the whole file:

magery.render_component("my-component", data)
magery.render_file("path/to/file.html", data)

@caolan caolan changed the title Terminology: pages vs. components Terminology: files vs. components Feb 8, 2018
@caolan caolan changed the title Terminology: files vs. components Terminology: pages vs. components Feb 8, 2018
@benzen
Copy link
Contributor

benzen commented Jan 5, 2019

It's not clear to me why we need a page concept.

I think react use only components it allow to define content of the body and stuff in the header two (i think).

What would pages bring to the table ? Except beeing a top level component ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
discussion
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@caolan @benzen