Sweetalert2: [Discussion] Rework Github Page

[acupofjose]

In an effort to keep the github page from becoming too cluttered, would it be worth pursuing separation of topics (alerts, toasts, methods, styles, getting started, etc.) out into pages? Adding a sticky navigational menu?

Much of the online presence for swal2 is pushed through the github page and imho the page is working its way towards becoming overwhelming.

Thoughts?

[zenflow]

Another update I'd like to see to the Github page: Examples using ES-next features (e.g., const, destructuring, async functions).

When using async functions, use of this package is way simplified (as are most async things), and more closely resembles the old-school alert, prompt, confirm function usage. Consider the following:

Using window.alert

function sayStuff () {
  alert('Hi')
  alert('I like turtles')
}

Using sweetalert2

function sayStuff () {
  return swal('Hi').then(function(){
    return swal('I like turtles')
  })
}

Using sweetalert2 with async functions

async function sayStuff () {
  await swal('Hi')
  await swal('I like turtles')
}

Obviously not everyone is able to use ES-next features; Would it be worth showing the examples in either (ES5 or ES-next) form, depending on the user's preference?

[toverux]

Obviously not everyone is able to use ES-next features; Would it be worth showing the examples in either (ES5 or ES-next) form, depending on the user's preference?

Ihmo, we should use the new language syntaxes and features everywhere by default now (I wouldn't have said that a year ago). A lot of people are using build tools nowadays, and/or modern browsers already show very good support of ES 15/16/17 features, including async/await. Unless you want to support IE and don't run a transpiler, it's safe to use modern JavaScript.
The web used to be a poor platform and we've got used to restrict ourselves from using new feature to support outdated browsers because that was a common things back in the days.

In fact, we've already seen, in Swal2 issues, people that were struggling with this in callbacks of then(), preConfirm, etc, because they copy-pasted function() { examples from the docs. We told them to use () => { and so far, nobody came back to say "but hey, I'm gettin a syntax error with your strange syntax".

If that happens to cause friction (= we get issues from confused people), then we may think about translating examples to ES 5.

[zenflow]

@toverux You make a good argument for the wide availability of modern js features.. so much that I don't think it's worth any effort to accommodate that narrow use-case (required support for IE but no transpilation). I'm sure a bigger issue is developers becoming familiar with the features and putting them to use - something we can help with by demonstrating them. For that narrow use-case where ES-next really can't be used, it should be on that programmer to translate our modern JS to their old IE-constrained JS

[zenflow]

+1 for @acupajoe's idea to organize the page into sections and add a navigation component, btw

[zenflow]

Bottom line: if you need to support IE (god have mercy on you), you should learn to transpile, and learn the latest features (most importantly async functions!) if you havent already.

EcmaScript 2015 + EcmaScript 2016+

[zenflow]

And even if you can't or aren't allowed to transpile, still learn the language features

[acupofjose]

Awesome, it seems like there is a consensus that this is needed. I'm happy to work on whatever is decided. I think it would be most effective to get an agreed upon mockup before continuing, so that everyone can piecewise contribute (should you feel so inclined!)

So - if you have the time! Submit your mockup ideas! @limonte @toverux @zenflow

[toverux]

Ideas of categories:
1) Installation
2) Basic examples (a few examples of a few LoCs at most to show the most common use cases), to get started quickly
2) Anatomy of a SweetAlert (show a SweetAlert with arrows pointing at elements, showing the related options and CSS classes to target)
3) Lifecycle of a Swal (explain how to handle results, dismissals, errors, preConfirm, etc, and oh, almost forgot it - queues...)
4) Modals, vs Non-Modal-Modals vs Toasts. Explain the target user experience and show usage.
5) Configuration reference - rather than a (growing) big list of options, group them by feature.
6) swal.* functions reference (maybe we should merge it with the options?)

Et voilà. I'd prefer a well-structured doc that explains the things correctly so the users can get the most out of SweetAlert, with good guidance via sort of cookbooks, rather than big lists of options.

Of course, that should stay very visual,compact, straightforward. The user should be able to understand how to fire an alert in the viewport at y=0, without scrolling, but it should also be able to find more informations about specific use cases, or how to avoid misuses for examples (eg. explain when to choose a toast over a modal).

Here's for the vision :smile: I'll try to come up with some drawings if I can materialize what I have in mind (I'm not very comfortable with any tools to do that and most mockup softwares are webapp/mobile apps-oriented)

[acupofjose]

Here's the layout/scheme I had in my head. Thoughts?

[limonte]

I totally like it the front page! :heart_eyes:

It will also look nice for mobile devices with wrapping the 'TOASTS' sections below the 'MODALS' section.

[toverux]

I like the colors, the overall theme and the overview of the modal and the toasts!
Maybe there's just a bit too much unused space, and the header is very large while not displaying useful information. Ihmo the npm/bower commands don't need to be the first thing we see and/or take the full screen - the modals + toasts block can be moved to the top, a bit like here, hehe (I especially like the orange zone, very engaging, for the rest we can do better though).

[acupofjose]

@toverux can't say I wasn't inspired by that haha - thank you for the feedback! I'll have the time this week to start modeling this stuff out in html instead of in sketch. I'll push it to a dev branch here to allow everyone else to contribute to it as well!

[KrunchMuffin]

Not a fan of the separate pages. Noty did that and I dislike it. I like being able to do CTRL+F to find something on the page. But I am for better organization. But that's just me.

[zenflow]

Not a fan of the separate pages. Noty did that and I dislike it. I like being able to do CTRL+F to find something on the page. But I am for better organization. But that's just me.

Perhaps we could have the best of both worlds, if we have everything on a single page but separated into sections, and users can still navigate & link to the different sections with hashtag routing, like this.

[zenflow]

So now that we have a sweetalert2 org (🎉) should the new documentation site be moved to a separate repository?

Advantages:

• Each repo would be more focused and limited in scope
• The documentation site could cover the core package and the framework integration packages, which would be convenient for users

Disadvantages:

• Coordinating updates between the code and the docs would become more tedious (For example, you could not any longer add/change/remove a param with a single commit, or by merging a single branch; you would have to make changes in two separate repos)

I'm not really sure at the moment which I would prefer.

[limonte]

So now that we have a sweetalert2 org (:tada:) should the new documentation site be moved to a separate repository?

Yes. https://github.com/sweetalert2/sweetalert2.github.io

[zenflow]

Idea: It would be cool to use something like Codemirror for examples, but where you can execute/modify/execute the code. I absolutely <3 Semantic UI React's documentation site for this. https://react.semantic-ui.com/elements/button#button-example-labeled There are some other nifty features for the code samples there too.

[zenflow]

This issue is getting a bit cluttered. Let's try to move the discussion into separate issues in the new sweetalert2/sweetalert2.github.io repo

[acupofjose]

I'm going to close this in favor of @zenflow's suggestion of moving to the new repo's issues

[zenflow]

Reminder to @toverux & @acupajoe .. "watch" the new repo if you want to get those notifications