search

fresh-standard / fresh-themes

Multiformat themes and skins for your technical résumé/CV.
MIT License
194 stars 63 forks source link

Updates to existing partials #45

Open evanplaice opened 8 years ago

evanplaice commented 8 years ago

Update: due to changes to FRESCA

education

references

samples

affiliation

governance

interests

hacksalot commented 8 years ago

Thanks, agreed. I think education has highlights in the latest schema.

Once the "add partial XYZ" updates are complete, we'll refactor again, stripping out some of the cruft and making the partials a bit more agnostic and policy-free than they are now. For example, there's no real reason the section/projects partials should impose a <section> container element. You may like <section>, I may like <section>, but the partial should impose as little structure as possible. Stuff like that.

evanplaice commented 8 years ago

@hacksalot I'm just making of the little discrepancies as I go. Most, if not all have been addressed thus far.

I just finished implementing all of the default partials, 'modern' theme, and models for everything. As soon as it's ready I plan to extract the component out into its own project.

Honestly, I don't think using <section> is an issue. According to HTML5, there's no issue with a page containing multiple sections.

In Angular2, components are basically custom html elements so my entire app is structure. Aside from removing the <html> and <head> tags, the major problem I've had so far is relative css tags that rely on a specific structure.

IMHO, the section tags should stay but a class should be added to indicate that they belong to fresh-resume. That way, css tags can target specific sections by id and all sections by class.

For example here's the testimonials template (since it's the simplest):

  <hr>
  <section id="testimonials" class="fresh-resume">
    <header title="Testimonials"><span class="fa fa-lg fa-thumbs-o-up"></span></header>
    <div *ngFor="#testimonial of testimonials">
      <h3><em>{{ testimonial.name }}</em></h3>
      <summary>{{ testimonial.quote }}</summary>
    </div>
  </section>

On non-descriptive relative CSS:

#main > #container > section {
  margin-left: 5em;
  position: relative;
  display: block;
}

Has the potential to cause a lot of problems, that can be difficult to reason about if the template is incorporated into a relatively complicated site. Like I said before, I have the sandbox the resume CSS using the Shadow DOM so it doesn't break the layout of my site.

The same could be replaced with: On non-descriptive relative CSS:

section .fresh-resume {
  margin-left: 5em;
  position: relative;
  display: block;
}

section #testimonials {
  /* testimonial-specific styling here */
}

...and it becomes immediately obvious what the styling applies to.

hacksalot commented 8 years ago

I need to push out an interim themes release to support HMR 1.6.0 and will roll with the proposed CSS changes for the next fresh-themes version ahead of the 1.0.0. To be clear, are you additionally suggesting Shadow DOM-related changes here or just the nominal CSS refactoring?

Re: <section>. There's a nice semantic connection between resume sections and HTML 5 <section> elements, but then you run into slightly older rendering systems and parsers that don't respect <section> as a proper block-level element. Or users who want <section><div> but don't want to override the entire section template. Or conventions around view rendering and markup when factoring into an MVC or MV* framework. But <section> would still be the default. We'd just add the ability to override in the tooling.

Let me know if you run into any other issues with integration/extraction, thanks for the Angular perspective here.

evanplaice commented 8 years ago

To be clear, are you additionally suggesting Shadow DOM-related changes here or just the nominal CSS refactoring?

It's up to you really. If you're aiming for release, don't worry about it.

older rendering systems and parsers that don't respect <section>

Damn... forgot about that. Why not just reference by CSS class? Then it doesn't matter whether it's a <section> or <div>. Or, alternatively you could experiment with setting section as a block-level element explicitly using CSS. Ala display: block.

hacksalot commented 8 years ago

An iterative release, not a waterfall freeze-everything release. I'd guesstimate most of the above would be in place in the next 1-2 days. The CSS is still a bit of a mess - lots of 4am coding, no Sass or LESS support yet (at least, no built-in support), my own bad programming, etc. But pretty easy to clean.

Why not just reference by CSS class?

Yeah I think that should handle most of the context breakage. I've been waiting on CSS refactoring for a) template expansion of CSS files, which now exists, and b) a Sass/LESS translation step, which will be added shortly. Since both of those will end up influencing the structure.

evanplaice commented 8 years ago

@hacksalot Yeah... CSS hierarchies would be a lot easier with SASS/LESS.

On an unrelated note. I converted the Jane Q. Fullstacker example to work with the FRESH format. https://github.com/evanplaice/evanplaice.com/blob/master/content/vitae/jane-q-fullstacker.json

I also have models available that cover the entire schema. https://github.com/evanplaice/evanplaice.com/tree/master/app/resume/shared/models

I'm almost ready to extract the resume portion of my site into a separate project.

hacksalot commented 8 years ago

Nice clean model structure. The flavor fields have been replaced with category, possibly a few other minor changes, but otherwise this looks clean. Keep me posted!

Not sure if this is relevant to your case but Jane was the original FRESH resume:

https://github.com/fluentdesk/jane-q-fullstacker

We did a conversion to JRS to support side-by-side testing but the canonical version is FRESH.

evanplaice commented 8 years ago

Damn... I was working off of the master branch. I should've checked dev. The same could be accomplished with 1/100th the code but I want finer grained control to add input type checking later.

Once the ng2 module is successfully extracted and hosted as an independent project, I plan to split out the modules as a separate project. That way, it's trivial to import them for reuse on both the client-side and server-side.

Damn... I just realized that I grabbed the JRS version. Derp.

What will JRS support look like in the future? Will FRESH be the 'everything and the kitchen sink' superset to JRS?

hacksalot commented 8 years ago

Not a big deal. I probably should've been more clear about the amount of work happening on dev.

HackMyResume will provide full support for JRS 1.0.0 when it drops, but we'll also be supporting...

Translations between the disparate formats are a lot easier if you have a universal container format that won't lose data. That format is FRESH. Since it's a superset format, we can also put a lot of analysis and validation-related stuff into FRESH that wouldn't fly in a standard like HR XML or JRS. It's not a competing format but a complimentary one.

evanplaice commented 8 years ago

@hacksalot It's all good. The hard was modeling everything from scratch. Adjusting things a bit gave me an opportunity to get a second look and fill the stuff I missed on the first pass.

I like the ambition. Data conversion tools should be pretty easy to implement since most of the formats follow the same general structure.

I actually suggested to JRS that they should include validation with their schema repo but the maintainers rejected the suggestion because validation was already tied to the JRS CLI tool. I tried the CLI tool and... well, that's the reason I ended up on HMR.

hacksalot commented 8 years ago

I don't contribute to (or even follow) JRS anymore, beyond keeping an eye out for the 1.0.0 when it drops. We didn't get a lot of support (= any) from them when HackMyResume dropped, despite shipping with support for JRS 0.0.0 above and beyond what their own tools offered, and I suspect the reason is because HackMyResume performs local resume generation, whereas the JRS tool appears to specifically have been built to silently upload user data to a remote registry with every export. Throw in their Hired.com sponsorship (a little early in the cycle for commercial endorsement, methinks, if FOSS is the real goal), not to mention the casual silent upload of user data, plus the general (top-down) tone of discussion, and JRS is not my first choice for a be-all end-all standard. I wish them well, and we'll support their formats as long as users call for them, but FRESH is actually a user-first system, albeit one with a different focus. Not a system that pays lip service to being user-first.

hacksalot commented 8 years ago

The validation component is called RedPen. It's built on a system of YAML-driven rules. A simple "Hello World" example for a game developer:

description: Resume warnings and advice for game developers.
author: FluentCV
inherit: coder
rules:
  - condition: "sheet.hasSkill('Unity') || sheet.hasSkill('Unreal') || sheet.hasSkill('CryEngine')"
    brief: This resume lacks experience with one of the Big 3 gaming engines. Consider learning Unreal, Unity, CryEngine, or another flagship game production toolset.
    moniker: know-your-engines
    overtone: warning

  - condition: "sheet.demo"
    brief: This resume doesn't mention a playable game demo of your own device. A playable demo can be an essential asset for landing a game development job.
    moniker: have-a-demo
    overtone: danger

HMR will take this, compile the ruleset, apply it, and display industry-specific LINT that users can tweak, configure, or ignore entirely. For starters. We also support JSON rulesets. And because all of this starts to become overkill for a simple resume, we provide the same system of validating templates (under another tool) for all document types. Hence the "Fluent" in FluentDesk.

evanplaice commented 8 years ago

@hacksalot I knew JRS had the option to upload a resume, I didn't realize it uploads silently by default. What a scummy thing to do.

I noticed the top-down discussion. Three users in particular that seem to have assumed control of the project despite contributing little-to-no actual code. As soon as I realized how toxic the project is I noped out and went ghost mode (ie deleted all comments/references).

As for the validation scheme. Wow! No exaggeration, that's amazing. I didn't realize tools existed that could generate linters so easily. I figured it would take something like jison + custom EBNF to validate the input data.

BTW, I decoupled the feature I've been working on to work as a standalone <ng2-resume> component and created a demo project that can be seen in action here.

As soon as angular drops the next release. It'll add relative path support for component-specific templates/css, of which the component uses a lot.

hacksalot commented 8 years ago

Took the liberty of grabbing a fork of that -- so this will work as a drop-in component with any FRESH model? Sweet. I had thought there was a direct dependency on fresh-themes but I see you've factored that in. We should be opening up a new round of themes shortly, a couple of which are experimental 3D themes under WebGL/Three.js that it would be fun to see in this context.

evanplaice commented 8 years ago

@hacksalot NG2 uses it's own html-like templating, so the fresh-themes couldn't be used directly.

I use facades to hide the messy details. Themes can be composed of default partials and/or use their own partials. The modular nature of Angular2 makes things really nice. If you want to try changing the theme look up the constants under resume/resume.js.

The data is loaded within the component that consumes the resume component so users never have to see the inner workings. All of the components and subcomponents are also fully fault tolerant. If a section has no data it won't appear. As far as structure goes, everything should match 1:1 with fresh-themes.

I don't really have much else to add for now other than extracting the models into a separate project and publishing the resume component to the JSPM registry. I just need Google drop the next damn release to fix that bug.

I'll be interested to see how the 3D themes look. Hopefully, they won't be too painful to implement.